diff --git a/content/sensu-go/6.8/_index.md b/archived/sensu-go/6.8/_index.md similarity index 100% rename from content/sensu-go/6.8/_index.md rename to archived/sensu-go/6.8/_index.md diff --git a/content/sensu-go/6.8/api/_index.md b/archived/sensu-go/6.8/api/_index.md similarity index 100% rename from content/sensu-go/6.8/api/_index.md rename to archived/sensu-go/6.8/api/_index.md diff --git a/content/sensu-go/6.8/api/core/_index.md b/archived/sensu-go/6.8/api/core/_index.md similarity index 100% rename from content/sensu-go/6.8/api/core/_index.md rename to archived/sensu-go/6.8/api/core/_index.md diff --git a/content/sensu-go/6.8/api/core/apikeys.md b/archived/sensu-go/6.8/api/core/apikeys.md similarity index 100% rename from content/sensu-go/6.8/api/core/apikeys.md rename to archived/sensu-go/6.8/api/core/apikeys.md diff --git a/content/sensu-go/6.8/api/core/assets.md b/archived/sensu-go/6.8/api/core/assets.md similarity index 100% rename from content/sensu-go/6.8/api/core/assets.md rename to archived/sensu-go/6.8/api/core/assets.md diff --git a/content/sensu-go/6.8/api/core/checks.md b/archived/sensu-go/6.8/api/core/checks.md similarity index 100% rename from content/sensu-go/6.8/api/core/checks.md rename to archived/sensu-go/6.8/api/core/checks.md diff --git a/content/sensu-go/6.8/api/core/cluster-role-bindings.md b/archived/sensu-go/6.8/api/core/cluster-role-bindings.md similarity index 100% rename from content/sensu-go/6.8/api/core/cluster-role-bindings.md rename to archived/sensu-go/6.8/api/core/cluster-role-bindings.md diff --git a/content/sensu-go/6.8/api/core/cluster-roles.md b/archived/sensu-go/6.8/api/core/cluster-roles.md similarity index 100% rename from content/sensu-go/6.8/api/core/cluster-roles.md rename to archived/sensu-go/6.8/api/core/cluster-roles.md diff --git a/content/sensu-go/6.8/api/core/cluster.md b/archived/sensu-go/6.8/api/core/cluster.md similarity index 100% rename from content/sensu-go/6.8/api/core/cluster.md rename to archived/sensu-go/6.8/api/core/cluster.md diff --git a/content/sensu-go/6.8/api/core/entities.md b/archived/sensu-go/6.8/api/core/entities.md similarity index 100% rename from content/sensu-go/6.8/api/core/entities.md rename to archived/sensu-go/6.8/api/core/entities.md diff --git a/content/sensu-go/6.8/api/core/events.md b/archived/sensu-go/6.8/api/core/events.md similarity index 100% rename from content/sensu-go/6.8/api/core/events.md rename to archived/sensu-go/6.8/api/core/events.md diff --git a/content/sensu-go/6.8/api/core/filters.md b/archived/sensu-go/6.8/api/core/filters.md similarity index 100% rename from content/sensu-go/6.8/api/core/filters.md rename to archived/sensu-go/6.8/api/core/filters.md diff --git a/content/sensu-go/6.8/api/core/handlers.md b/archived/sensu-go/6.8/api/core/handlers.md similarity index 100% rename from content/sensu-go/6.8/api/core/handlers.md rename to archived/sensu-go/6.8/api/core/handlers.md diff --git a/content/sensu-go/6.8/api/core/hooks.md b/archived/sensu-go/6.8/api/core/hooks.md similarity index 100% rename from content/sensu-go/6.8/api/core/hooks.md rename to archived/sensu-go/6.8/api/core/hooks.md diff --git a/content/sensu-go/6.8/api/core/mutators.md b/archived/sensu-go/6.8/api/core/mutators.md similarity index 100% rename from content/sensu-go/6.8/api/core/mutators.md rename to archived/sensu-go/6.8/api/core/mutators.md diff --git a/content/sensu-go/6.8/api/core/namespaces.md b/archived/sensu-go/6.8/api/core/namespaces.md similarity index 100% rename from content/sensu-go/6.8/api/core/namespaces.md rename to archived/sensu-go/6.8/api/core/namespaces.md diff --git a/content/sensu-go/6.8/api/core/pipelines.md b/archived/sensu-go/6.8/api/core/pipelines.md similarity index 100% rename from content/sensu-go/6.8/api/core/pipelines.md rename to archived/sensu-go/6.8/api/core/pipelines.md diff --git a/content/sensu-go/6.8/api/core/role-bindings.md b/archived/sensu-go/6.8/api/core/role-bindings.md similarity index 100% rename from content/sensu-go/6.8/api/core/role-bindings.md rename to archived/sensu-go/6.8/api/core/role-bindings.md diff --git a/content/sensu-go/6.8/api/core/roles.md b/archived/sensu-go/6.8/api/core/roles.md similarity index 100% rename from content/sensu-go/6.8/api/core/roles.md rename to archived/sensu-go/6.8/api/core/roles.md diff --git a/content/sensu-go/6.8/api/core/silenced.md b/archived/sensu-go/6.8/api/core/silenced.md similarity index 100% rename from content/sensu-go/6.8/api/core/silenced.md rename to archived/sensu-go/6.8/api/core/silenced.md diff --git a/content/sensu-go/6.8/api/core/tessen.md b/archived/sensu-go/6.8/api/core/tessen.md similarity index 100% rename from content/sensu-go/6.8/api/core/tessen.md rename to archived/sensu-go/6.8/api/core/tessen.md diff --git a/content/sensu-go/6.8/api/core/users.md b/archived/sensu-go/6.8/api/core/users.md similarity index 100% rename from content/sensu-go/6.8/api/core/users.md rename to archived/sensu-go/6.8/api/core/users.md diff --git a/content/sensu-go/6.8/api/enterprise/_index.md b/archived/sensu-go/6.8/api/enterprise/_index.md similarity index 100% rename from content/sensu-go/6.8/api/enterprise/_index.md rename to archived/sensu-go/6.8/api/enterprise/_index.md diff --git a/content/sensu-go/6.8/api/enterprise/authproviders.md b/archived/sensu-go/6.8/api/enterprise/authproviders.md similarity index 100% rename from content/sensu-go/6.8/api/enterprise/authproviders.md rename to archived/sensu-go/6.8/api/enterprise/authproviders.md diff --git a/content/sensu-go/6.8/api/enterprise/business-service-monitoring.md b/archived/sensu-go/6.8/api/enterprise/business-service-monitoring.md similarity index 100% rename from content/sensu-go/6.8/api/enterprise/business-service-monitoring.md rename to archived/sensu-go/6.8/api/enterprise/business-service-monitoring.md diff --git a/content/sensu-go/6.8/api/enterprise/datastore.md b/archived/sensu-go/6.8/api/enterprise/datastore.md similarity index 100% rename from content/sensu-go/6.8/api/enterprise/datastore.md rename to archived/sensu-go/6.8/api/enterprise/datastore.md diff --git a/content/sensu-go/6.8/api/enterprise/federation.md b/archived/sensu-go/6.8/api/enterprise/federation.md similarity index 100% rename from content/sensu-go/6.8/api/enterprise/federation.md rename to archived/sensu-go/6.8/api/enterprise/federation.md diff --git a/content/sensu-go/6.8/api/enterprise/pipeline.md b/archived/sensu-go/6.8/api/enterprise/pipeline.md similarity index 100% rename from content/sensu-go/6.8/api/enterprise/pipeline.md rename to archived/sensu-go/6.8/api/enterprise/pipeline.md diff --git a/content/sensu-go/6.8/api/enterprise/prune.md b/archived/sensu-go/6.8/api/enterprise/prune.md similarity index 100% rename from content/sensu-go/6.8/api/enterprise/prune.md rename to archived/sensu-go/6.8/api/enterprise/prune.md diff --git a/content/sensu-go/6.8/api/enterprise/searches.md b/archived/sensu-go/6.8/api/enterprise/searches.md similarity index 100% rename from content/sensu-go/6.8/api/enterprise/searches.md rename to archived/sensu-go/6.8/api/enterprise/searches.md diff --git a/content/sensu-go/6.8/api/enterprise/secrets.md b/archived/sensu-go/6.8/api/enterprise/secrets.md similarity index 100% rename from content/sensu-go/6.8/api/enterprise/secrets.md rename to archived/sensu-go/6.8/api/enterprise/secrets.md diff --git a/content/sensu-go/6.8/api/enterprise/webconfig.md b/archived/sensu-go/6.8/api/enterprise/webconfig.md similarity index 100% rename from content/sensu-go/6.8/api/enterprise/webconfig.md rename to archived/sensu-go/6.8/api/enterprise/webconfig.md diff --git a/content/sensu-go/6.8/api/other/_index.md b/archived/sensu-go/6.8/api/other/_index.md similarity index 100% rename from content/sensu-go/6.8/api/other/_index.md rename to archived/sensu-go/6.8/api/other/_index.md diff --git a/content/sensu-go/6.8/api/other/auth.md b/archived/sensu-go/6.8/api/other/auth.md similarity index 100% rename from content/sensu-go/6.8/api/other/auth.md rename to archived/sensu-go/6.8/api/other/auth.md diff --git a/content/sensu-go/6.8/api/other/health.md b/archived/sensu-go/6.8/api/other/health.md similarity index 100% rename from content/sensu-go/6.8/api/other/health.md rename to archived/sensu-go/6.8/api/other/health.md diff --git a/content/sensu-go/6.8/api/other/license.md b/archived/sensu-go/6.8/api/other/license.md similarity index 100% rename from content/sensu-go/6.8/api/other/license.md rename to archived/sensu-go/6.8/api/other/license.md diff --git a/content/sensu-go/6.8/api/other/metrics.md b/archived/sensu-go/6.8/api/other/metrics.md similarity index 100% rename from content/sensu-go/6.8/api/other/metrics.md rename to archived/sensu-go/6.8/api/other/metrics.md diff --git a/content/sensu-go/6.8/api/other/ready.md b/archived/sensu-go/6.8/api/other/ready.md similarity index 100% rename from content/sensu-go/6.8/api/other/ready.md rename to archived/sensu-go/6.8/api/other/ready.md diff --git a/content/sensu-go/6.8/api/other/version.md b/archived/sensu-go/6.8/api/other/version.md similarity index 100% rename from content/sensu-go/6.8/api/other/version.md rename to archived/sensu-go/6.8/api/other/version.md diff --git a/content/sensu-go/6.8/catalog/_index.md b/archived/sensu-go/6.8/catalog/_index.md similarity index 100% rename from content/sensu-go/6.8/catalog/_index.md rename to archived/sensu-go/6.8/catalog/_index.md diff --git a/content/sensu-go/6.8/catalog/build-private-catalog.md b/archived/sensu-go/6.8/catalog/build-private-catalog.md similarity index 100% rename from content/sensu-go/6.8/catalog/build-private-catalog.md rename to archived/sensu-go/6.8/catalog/build-private-catalog.md diff --git a/content/sensu-go/6.8/catalog/catalog-api.md b/archived/sensu-go/6.8/catalog/catalog-api.md similarity index 100% rename from content/sensu-go/6.8/catalog/catalog-api.md rename to archived/sensu-go/6.8/catalog/catalog-api.md diff --git a/content/sensu-go/6.8/catalog/catalog-reference.md b/archived/sensu-go/6.8/catalog/catalog-reference.md similarity index 100% rename from content/sensu-go/6.8/catalog/catalog-reference.md rename to archived/sensu-go/6.8/catalog/catalog-reference.md diff --git a/content/sensu-go/6.8/catalog/sensu-catalog.md b/archived/sensu-go/6.8/catalog/sensu-catalog.md similarity index 100% rename from content/sensu-go/6.8/catalog/sensu-catalog.md rename to archived/sensu-go/6.8/catalog/sensu-catalog.md diff --git a/content/sensu-go/6.8/commercial.md b/archived/sensu-go/6.8/commercial.md similarity index 100% rename from content/sensu-go/6.8/commercial.md rename to archived/sensu-go/6.8/commercial.md diff --git a/content/sensu-go/6.8/files/agent.yml b/archived/sensu-go/6.8/files/agent.yml similarity index 100% rename from content/sensu-go/6.8/files/agent.yml rename to archived/sensu-go/6.8/files/agent.yml diff --git a/content/sensu-go/6.8/files/backend.yml b/archived/sensu-go/6.8/files/backend.yml similarity index 100% rename from content/sensu-go/6.8/files/backend.yml rename to archived/sensu-go/6.8/files/backend.yml diff --git a/content/sensu-go/6.8/files/sensu-plus-dashboard-config.json b/archived/sensu-go/6.8/files/sensu-plus-dashboard-config.json similarity index 100% rename from content/sensu-go/6.8/files/sensu-plus-dashboard-config.json rename to archived/sensu-go/6.8/files/sensu-plus-dashboard-config.json diff --git a/content/sensu-go/6.8/files/up_or_down_dashboard.json b/archived/sensu-go/6.8/files/up_or_down_dashboard.json similarity index 100% rename from content/sensu-go/6.8/files/up_or_down_dashboard.json rename to archived/sensu-go/6.8/files/up_or_down_dashboard.json diff --git a/content/sensu-go/6.8/files/windows/agent.yml b/archived/sensu-go/6.8/files/windows/agent.yml similarity index 100% rename from content/sensu-go/6.8/files/windows/agent.yml rename to archived/sensu-go/6.8/files/windows/agent.yml diff --git a/content/sensu-go/6.8/get-started.md b/archived/sensu-go/6.8/get-started.md similarity index 100% rename from content/sensu-go/6.8/get-started.md rename to archived/sensu-go/6.8/get-started.md diff --git a/content/sensu-go/6.8/guides/_index.md b/archived/sensu-go/6.8/guides/_index.md similarity index 100% rename from content/sensu-go/6.8/guides/_index.md rename to archived/sensu-go/6.8/guides/_index.md diff --git a/content/sensu-go/6.8/learn/_index.md b/archived/sensu-go/6.8/learn/_index.md similarity index 100% rename from content/sensu-go/6.8/learn/_index.md rename to archived/sensu-go/6.8/learn/_index.md diff --git a/content/sensu-go/6.8/learn/concepts-terminology.md b/archived/sensu-go/6.8/learn/concepts-terminology.md similarity index 100% rename from content/sensu-go/6.8/learn/concepts-terminology.md rename to archived/sensu-go/6.8/learn/concepts-terminology.md diff --git a/content/sensu-go/6.8/learn/demo.md b/archived/sensu-go/6.8/learn/demo.md similarity index 100% rename from content/sensu-go/6.8/learn/demo.md rename to archived/sensu-go/6.8/learn/demo.md diff --git a/content/sensu-go/6.8/observability-pipeline/_index.md b/archived/sensu-go/6.8/observability-pipeline/_index.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/_index.md rename to archived/sensu-go/6.8/observability-pipeline/_index.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-entities/_index.md b/archived/sensu-go/6.8/observability-pipeline/observe-entities/_index.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-entities/_index.md rename to archived/sensu-go/6.8/observability-pipeline/observe-entities/_index.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-entities/auto-register-deregister.md b/archived/sensu-go/6.8/observability-pipeline/observe-entities/auto-register-deregister.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-entities/auto-register-deregister.md rename to archived/sensu-go/6.8/observability-pipeline/observe-entities/auto-register-deregister.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-entities/entities.md b/archived/sensu-go/6.8/observability-pipeline/observe-entities/entities.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-entities/entities.md rename to archived/sensu-go/6.8/observability-pipeline/observe-entities/entities.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-entities/monitor-external-resources.md b/archived/sensu-go/6.8/observability-pipeline/observe-entities/monitor-external-resources.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-entities/monitor-external-resources.md rename to archived/sensu-go/6.8/observability-pipeline/observe-entities/monitor-external-resources.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-events/_index.md b/archived/sensu-go/6.8/observability-pipeline/observe-events/_index.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-events/_index.md rename to archived/sensu-go/6.8/observability-pipeline/observe-events/_index.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-events/events.md b/archived/sensu-go/6.8/observability-pipeline/observe-events/events.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-events/events.md rename to archived/sensu-go/6.8/observability-pipeline/observe-events/events.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-filter/_index.md b/archived/sensu-go/6.8/observability-pipeline/observe-filter/_index.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-filter/_index.md rename to archived/sensu-go/6.8/observability-pipeline/observe-filter/_index.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-filter/filters.md b/archived/sensu-go/6.8/observability-pipeline/observe-filter/filters.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-filter/filters.md rename to archived/sensu-go/6.8/observability-pipeline/observe-filter/filters.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-filter/reduce-alert-fatigue.md b/archived/sensu-go/6.8/observability-pipeline/observe-filter/reduce-alert-fatigue.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-filter/reduce-alert-fatigue.md rename to archived/sensu-go/6.8/observability-pipeline/observe-filter/reduce-alert-fatigue.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-filter/route-alerts.md b/archived/sensu-go/6.8/observability-pipeline/observe-filter/route-alerts.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-filter/route-alerts.md rename to archived/sensu-go/6.8/observability-pipeline/observe-filter/route-alerts.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-filter/sensu-query-expressions.md b/archived/sensu-go/6.8/observability-pipeline/observe-filter/sensu-query-expressions.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-filter/sensu-query-expressions.md rename to archived/sensu-go/6.8/observability-pipeline/observe-filter/sensu-query-expressions.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-process/_index.md b/archived/sensu-go/6.8/observability-pipeline/observe-process/_index.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-process/_index.md rename to archived/sensu-go/6.8/observability-pipeline/observe-process/_index.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-process/aggregate-metrics-statsd.md b/archived/sensu-go/6.8/observability-pipeline/observe-process/aggregate-metrics-statsd.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-process/aggregate-metrics-statsd.md rename to archived/sensu-go/6.8/observability-pipeline/observe-process/aggregate-metrics-statsd.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-process/handler-templates.md b/archived/sensu-go/6.8/observability-pipeline/observe-process/handler-templates.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-process/handler-templates.md rename to archived/sensu-go/6.8/observability-pipeline/observe-process/handler-templates.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-process/handlers.md b/archived/sensu-go/6.8/observability-pipeline/observe-process/handlers.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-process/handlers.md rename to archived/sensu-go/6.8/observability-pipeline/observe-process/handlers.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-process/pipelines.md b/archived/sensu-go/6.8/observability-pipeline/observe-process/pipelines.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-process/pipelines.md rename to archived/sensu-go/6.8/observability-pipeline/observe-process/pipelines.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-process/plan-maintenance.md b/archived/sensu-go/6.8/observability-pipeline/observe-process/plan-maintenance.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-process/plan-maintenance.md rename to archived/sensu-go/6.8/observability-pipeline/observe-process/plan-maintenance.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-process/populate-metrics-influxdb.md b/archived/sensu-go/6.8/observability-pipeline/observe-process/populate-metrics-influxdb.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-process/populate-metrics-influxdb.md rename to archived/sensu-go/6.8/observability-pipeline/observe-process/populate-metrics-influxdb.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-process/send-data-sumo-logic.md b/archived/sensu-go/6.8/observability-pipeline/observe-process/send-data-sumo-logic.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-process/send-data-sumo-logic.md rename to archived/sensu-go/6.8/observability-pipeline/observe-process/send-data-sumo-logic.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-process/send-email-alerts.md b/archived/sensu-go/6.8/observability-pipeline/observe-process/send-email-alerts.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-process/send-email-alerts.md rename to archived/sensu-go/6.8/observability-pipeline/observe-process/send-email-alerts.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-process/send-pagerduty-alerts.md b/archived/sensu-go/6.8/observability-pipeline/observe-process/send-pagerduty-alerts.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-process/send-pagerduty-alerts.md rename to archived/sensu-go/6.8/observability-pipeline/observe-process/send-pagerduty-alerts.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-process/send-slack-alerts.md b/archived/sensu-go/6.8/observability-pipeline/observe-process/send-slack-alerts.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-process/send-slack-alerts.md rename to archived/sensu-go/6.8/observability-pipeline/observe-process/send-slack-alerts.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-process/silencing.md b/archived/sensu-go/6.8/observability-pipeline/observe-process/silencing.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-process/silencing.md rename to archived/sensu-go/6.8/observability-pipeline/observe-process/silencing.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-process/sumo-logic-metrics-handlers.md b/archived/sensu-go/6.8/observability-pipeline/observe-process/sumo-logic-metrics-handlers.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-process/sumo-logic-metrics-handlers.md rename to archived/sensu-go/6.8/observability-pipeline/observe-process/sumo-logic-metrics-handlers.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-process/tcp-stream-handlers.md b/archived/sensu-go/6.8/observability-pipeline/observe-process/tcp-stream-handlers.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-process/tcp-stream-handlers.md rename to archived/sensu-go/6.8/observability-pipeline/observe-process/tcp-stream-handlers.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-schedule/_index.md b/archived/sensu-go/6.8/observability-pipeline/observe-schedule/_index.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-schedule/_index.md rename to archived/sensu-go/6.8/observability-pipeline/observe-schedule/_index.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-schedule/agent.md b/archived/sensu-go/6.8/observability-pipeline/observe-schedule/agent.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-schedule/agent.md rename to archived/sensu-go/6.8/observability-pipeline/observe-schedule/agent.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-schedule/augment-event-data-with-hooks.md b/archived/sensu-go/6.8/observability-pipeline/observe-schedule/augment-event-data-with-hooks.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-schedule/augment-event-data-with-hooks.md rename to archived/sensu-go/6.8/observability-pipeline/observe-schedule/augment-event-data-with-hooks.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-schedule/backend.md b/archived/sensu-go/6.8/observability-pipeline/observe-schedule/backend.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-schedule/backend.md rename to archived/sensu-go/6.8/observability-pipeline/observe-schedule/backend.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-schedule/business-service-monitoring-sdk.md b/archived/sensu-go/6.8/observability-pipeline/observe-schedule/business-service-monitoring-sdk.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-schedule/business-service-monitoring-sdk.md rename to archived/sensu-go/6.8/observability-pipeline/observe-schedule/business-service-monitoring-sdk.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-schedule/business-service-monitoring.md b/archived/sensu-go/6.8/observability-pipeline/observe-schedule/business-service-monitoring.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-schedule/business-service-monitoring.md rename to archived/sensu-go/6.8/observability-pipeline/observe-schedule/business-service-monitoring.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-schedule/checks.md b/archived/sensu-go/6.8/observability-pipeline/observe-schedule/checks.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-schedule/checks.md rename to archived/sensu-go/6.8/observability-pipeline/observe-schedule/checks.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-schedule/collect-metrics-with-checks.md b/archived/sensu-go/6.8/observability-pipeline/observe-schedule/collect-metrics-with-checks.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-schedule/collect-metrics-with-checks.md rename to archived/sensu-go/6.8/observability-pipeline/observe-schedule/collect-metrics-with-checks.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-schedule/hooks.md b/archived/sensu-go/6.8/observability-pipeline/observe-schedule/hooks.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-schedule/hooks.md rename to archived/sensu-go/6.8/observability-pipeline/observe-schedule/hooks.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-schedule/metrics.md b/archived/sensu-go/6.8/observability-pipeline/observe-schedule/metrics.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-schedule/metrics.md rename to archived/sensu-go/6.8/observability-pipeline/observe-schedule/metrics.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-schedule/monitor-server-resources.md b/archived/sensu-go/6.8/observability-pipeline/observe-schedule/monitor-server-resources.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-schedule/monitor-server-resources.md rename to archived/sensu-go/6.8/observability-pipeline/observe-schedule/monitor-server-resources.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-schedule/prometheus-metrics.md b/archived/sensu-go/6.8/observability-pipeline/observe-schedule/prometheus-metrics.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-schedule/prometheus-metrics.md rename to archived/sensu-go/6.8/observability-pipeline/observe-schedule/prometheus-metrics.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-schedule/rule-templates.md b/archived/sensu-go/6.8/observability-pipeline/observe-schedule/rule-templates.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-schedule/rule-templates.md rename to archived/sensu-go/6.8/observability-pipeline/observe-schedule/rule-templates.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-schedule/service-components.md b/archived/sensu-go/6.8/observability-pipeline/observe-schedule/service-components.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-schedule/service-components.md rename to archived/sensu-go/6.8/observability-pipeline/observe-schedule/service-components.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-schedule/subscriptions.md b/archived/sensu-go/6.8/observability-pipeline/observe-schedule/subscriptions.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-schedule/subscriptions.md rename to archived/sensu-go/6.8/observability-pipeline/observe-schedule/subscriptions.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-schedule/tokens.md b/archived/sensu-go/6.8/observability-pipeline/observe-schedule/tokens.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-schedule/tokens.md rename to archived/sensu-go/6.8/observability-pipeline/observe-schedule/tokens.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-transform/_index.md b/archived/sensu-go/6.8/observability-pipeline/observe-transform/_index.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-transform/_index.md rename to archived/sensu-go/6.8/observability-pipeline/observe-transform/_index.md diff --git a/content/sensu-go/6.8/observability-pipeline/observe-transform/mutators.md b/archived/sensu-go/6.8/observability-pipeline/observe-transform/mutators.md similarity index 100% rename from content/sensu-go/6.8/observability-pipeline/observe-transform/mutators.md rename to archived/sensu-go/6.8/observability-pipeline/observe-transform/mutators.md diff --git a/content/sensu-go/6.8/operations/_index.md b/archived/sensu-go/6.8/operations/_index.md similarity index 100% rename from content/sensu-go/6.8/operations/_index.md rename to archived/sensu-go/6.8/operations/_index.md diff --git a/content/sensu-go/6.8/operations/control-access/_index.md b/archived/sensu-go/6.8/operations/control-access/_index.md similarity index 100% rename from content/sensu-go/6.8/operations/control-access/_index.md rename to archived/sensu-go/6.8/operations/control-access/_index.md diff --git a/content/sensu-go/6.8/operations/control-access/ad-auth.md b/archived/sensu-go/6.8/operations/control-access/ad-auth.md similarity index 100% rename from content/sensu-go/6.8/operations/control-access/ad-auth.md rename to archived/sensu-go/6.8/operations/control-access/ad-auth.md diff --git a/content/sensu-go/6.8/operations/control-access/apikeys.md b/archived/sensu-go/6.8/operations/control-access/apikeys.md similarity index 100% rename from content/sensu-go/6.8/operations/control-access/apikeys.md rename to archived/sensu-go/6.8/operations/control-access/apikeys.md diff --git a/content/sensu-go/6.8/operations/control-access/create-limited-service-accounts.md b/archived/sensu-go/6.8/operations/control-access/create-limited-service-accounts.md similarity index 100% rename from content/sensu-go/6.8/operations/control-access/create-limited-service-accounts.md rename to archived/sensu-go/6.8/operations/control-access/create-limited-service-accounts.md diff --git a/content/sensu-go/6.8/operations/control-access/create-read-only-user.md b/archived/sensu-go/6.8/operations/control-access/create-read-only-user.md similarity index 100% rename from content/sensu-go/6.8/operations/control-access/create-read-only-user.md rename to archived/sensu-go/6.8/operations/control-access/create-read-only-user.md diff --git a/content/sensu-go/6.8/operations/control-access/ldap-auth.md b/archived/sensu-go/6.8/operations/control-access/ldap-auth.md similarity index 100% rename from content/sensu-go/6.8/operations/control-access/ldap-auth.md rename to archived/sensu-go/6.8/operations/control-access/ldap-auth.md diff --git a/content/sensu-go/6.8/operations/control-access/namespaces.md b/archived/sensu-go/6.8/operations/control-access/namespaces.md similarity index 100% rename from content/sensu-go/6.8/operations/control-access/namespaces.md rename to archived/sensu-go/6.8/operations/control-access/namespaces.md diff --git a/content/sensu-go/6.8/operations/control-access/oidc-auth.md b/archived/sensu-go/6.8/operations/control-access/oidc-auth.md similarity index 100% rename from content/sensu-go/6.8/operations/control-access/oidc-auth.md rename to archived/sensu-go/6.8/operations/control-access/oidc-auth.md diff --git a/content/sensu-go/6.8/operations/control-access/rbac.md b/archived/sensu-go/6.8/operations/control-access/rbac.md similarity index 100% rename from content/sensu-go/6.8/operations/control-access/rbac.md rename to archived/sensu-go/6.8/operations/control-access/rbac.md diff --git a/content/sensu-go/6.8/operations/control-access/sso.md b/archived/sensu-go/6.8/operations/control-access/sso.md similarity index 100% rename from content/sensu-go/6.8/operations/control-access/sso.md rename to archived/sensu-go/6.8/operations/control-access/sso.md diff --git a/content/sensu-go/6.8/operations/control-access/use-apikeys.md b/archived/sensu-go/6.8/operations/control-access/use-apikeys.md similarity index 100% rename from content/sensu-go/6.8/operations/control-access/use-apikeys.md rename to archived/sensu-go/6.8/operations/control-access/use-apikeys.md diff --git a/content/sensu-go/6.8/operations/deploy-sensu/_index.md b/archived/sensu-go/6.8/operations/deploy-sensu/_index.md similarity index 100% rename from content/sensu-go/6.8/operations/deploy-sensu/_index.md rename to archived/sensu-go/6.8/operations/deploy-sensu/_index.md diff --git a/content/sensu-go/6.8/operations/deploy-sensu/cluster-sensu.md b/archived/sensu-go/6.8/operations/deploy-sensu/cluster-sensu.md similarity index 100% rename from content/sensu-go/6.8/operations/deploy-sensu/cluster-sensu.md rename to archived/sensu-go/6.8/operations/deploy-sensu/cluster-sensu.md diff --git a/content/sensu-go/6.8/operations/deploy-sensu/configuration-management.md b/archived/sensu-go/6.8/operations/deploy-sensu/configuration-management.md similarity index 100% rename from content/sensu-go/6.8/operations/deploy-sensu/configuration-management.md rename to archived/sensu-go/6.8/operations/deploy-sensu/configuration-management.md diff --git a/content/sensu-go/6.8/operations/deploy-sensu/datastore.md b/archived/sensu-go/6.8/operations/deploy-sensu/datastore.md similarity index 100% rename from content/sensu-go/6.8/operations/deploy-sensu/datastore.md rename to archived/sensu-go/6.8/operations/deploy-sensu/datastore.md diff --git a/content/sensu-go/6.8/operations/deploy-sensu/deployment-architecture.md b/archived/sensu-go/6.8/operations/deploy-sensu/deployment-architecture.md similarity index 100% rename from content/sensu-go/6.8/operations/deploy-sensu/deployment-architecture.md rename to archived/sensu-go/6.8/operations/deploy-sensu/deployment-architecture.md diff --git a/content/sensu-go/6.8/operations/deploy-sensu/etcdreplicators.md b/archived/sensu-go/6.8/operations/deploy-sensu/etcdreplicators.md similarity index 100% rename from content/sensu-go/6.8/operations/deploy-sensu/etcdreplicators.md rename to archived/sensu-go/6.8/operations/deploy-sensu/etcdreplicators.md diff --git a/content/sensu-go/6.8/operations/deploy-sensu/generate-certificates.md b/archived/sensu-go/6.8/operations/deploy-sensu/generate-certificates.md similarity index 100% rename from content/sensu-go/6.8/operations/deploy-sensu/generate-certificates.md rename to archived/sensu-go/6.8/operations/deploy-sensu/generate-certificates.md diff --git a/content/sensu-go/6.8/operations/deploy-sensu/hardware-requirements.md b/archived/sensu-go/6.8/operations/deploy-sensu/hardware-requirements.md similarity index 100% rename from content/sensu-go/6.8/operations/deploy-sensu/hardware-requirements.md rename to archived/sensu-go/6.8/operations/deploy-sensu/hardware-requirements.md diff --git a/content/sensu-go/6.8/operations/deploy-sensu/install-sensu.md b/archived/sensu-go/6.8/operations/deploy-sensu/install-sensu.md similarity index 100% rename from content/sensu-go/6.8/operations/deploy-sensu/install-sensu.md rename to archived/sensu-go/6.8/operations/deploy-sensu/install-sensu.md diff --git a/content/sensu-go/6.8/operations/deploy-sensu/scale-event-storage.md b/archived/sensu-go/6.8/operations/deploy-sensu/scale-event-storage.md similarity index 100% rename from content/sensu-go/6.8/operations/deploy-sensu/scale-event-storage.md rename to archived/sensu-go/6.8/operations/deploy-sensu/scale-event-storage.md diff --git a/content/sensu-go/6.8/operations/deploy-sensu/secure-postgres.md b/archived/sensu-go/6.8/operations/deploy-sensu/secure-postgres.md similarity index 100% rename from content/sensu-go/6.8/operations/deploy-sensu/secure-postgres.md rename to archived/sensu-go/6.8/operations/deploy-sensu/secure-postgres.md diff --git a/content/sensu-go/6.8/operations/deploy-sensu/secure-sensu.md b/archived/sensu-go/6.8/operations/deploy-sensu/secure-sensu.md similarity index 100% rename from content/sensu-go/6.8/operations/deploy-sensu/secure-sensu.md rename to archived/sensu-go/6.8/operations/deploy-sensu/secure-sensu.md diff --git a/content/sensu-go/6.8/operations/deploy-sensu/use-federation.md b/archived/sensu-go/6.8/operations/deploy-sensu/use-federation.md similarity index 100% rename from content/sensu-go/6.8/operations/deploy-sensu/use-federation.md rename to archived/sensu-go/6.8/operations/deploy-sensu/use-federation.md diff --git a/content/sensu-go/6.8/operations/maintain-sensu/_index.md b/archived/sensu-go/6.8/operations/maintain-sensu/_index.md similarity index 100% rename from content/sensu-go/6.8/operations/maintain-sensu/_index.md rename to archived/sensu-go/6.8/operations/maintain-sensu/_index.md diff --git a/content/sensu-go/6.8/operations/maintain-sensu/disaster-recovery.md b/archived/sensu-go/6.8/operations/maintain-sensu/disaster-recovery.md similarity index 100% rename from content/sensu-go/6.8/operations/maintain-sensu/disaster-recovery.md rename to archived/sensu-go/6.8/operations/maintain-sensu/disaster-recovery.md diff --git a/content/sensu-go/6.8/operations/maintain-sensu/license.md b/archived/sensu-go/6.8/operations/maintain-sensu/license.md similarity index 100% rename from content/sensu-go/6.8/operations/maintain-sensu/license.md rename to archived/sensu-go/6.8/operations/maintain-sensu/license.md diff --git a/content/sensu-go/6.8/operations/maintain-sensu/migrate.md b/archived/sensu-go/6.8/operations/maintain-sensu/migrate.md similarity index 100% rename from content/sensu-go/6.8/operations/maintain-sensu/migrate.md rename to archived/sensu-go/6.8/operations/maintain-sensu/migrate.md diff --git a/content/sensu-go/6.8/operations/maintain-sensu/troubleshoot.md b/archived/sensu-go/6.8/operations/maintain-sensu/troubleshoot.md similarity index 100% rename from content/sensu-go/6.8/operations/maintain-sensu/troubleshoot.md rename to archived/sensu-go/6.8/operations/maintain-sensu/troubleshoot.md diff --git a/content/sensu-go/6.8/operations/maintain-sensu/tune.md b/archived/sensu-go/6.8/operations/maintain-sensu/tune.md similarity index 100% rename from content/sensu-go/6.8/operations/maintain-sensu/tune.md rename to archived/sensu-go/6.8/operations/maintain-sensu/tune.md diff --git a/content/sensu-go/6.8/operations/maintain-sensu/upgrade.md b/archived/sensu-go/6.8/operations/maintain-sensu/upgrade.md similarity index 100% rename from content/sensu-go/6.8/operations/maintain-sensu/upgrade.md rename to archived/sensu-go/6.8/operations/maintain-sensu/upgrade.md diff --git a/content/sensu-go/6.8/operations/manage-secrets/_index.md b/archived/sensu-go/6.8/operations/manage-secrets/_index.md similarity index 100% rename from content/sensu-go/6.8/operations/manage-secrets/_index.md rename to archived/sensu-go/6.8/operations/manage-secrets/_index.md diff --git a/content/sensu-go/6.8/operations/manage-secrets/secrets-management.md b/archived/sensu-go/6.8/operations/manage-secrets/secrets-management.md similarity index 100% rename from content/sensu-go/6.8/operations/manage-secrets/secrets-management.md rename to archived/sensu-go/6.8/operations/manage-secrets/secrets-management.md diff --git a/content/sensu-go/6.8/operations/manage-secrets/secrets-providers.md b/archived/sensu-go/6.8/operations/manage-secrets/secrets-providers.md similarity index 100% rename from content/sensu-go/6.8/operations/manage-secrets/secrets-providers.md rename to archived/sensu-go/6.8/operations/manage-secrets/secrets-providers.md diff --git a/content/sensu-go/6.8/operations/manage-secrets/secrets.md b/archived/sensu-go/6.8/operations/manage-secrets/secrets.md similarity index 100% rename from content/sensu-go/6.8/operations/manage-secrets/secrets.md rename to archived/sensu-go/6.8/operations/manage-secrets/secrets.md diff --git a/content/sensu-go/6.8/operations/monitor-sensu/_index.md b/archived/sensu-go/6.8/operations/monitor-sensu/_index.md similarity index 100% rename from content/sensu-go/6.8/operations/monitor-sensu/_index.md rename to archived/sensu-go/6.8/operations/monitor-sensu/_index.md diff --git a/content/sensu-go/6.8/operations/monitor-sensu/health.md b/archived/sensu-go/6.8/operations/monitor-sensu/health.md similarity index 100% rename from content/sensu-go/6.8/operations/monitor-sensu/health.md rename to archived/sensu-go/6.8/operations/monitor-sensu/health.md diff --git a/content/sensu-go/6.8/operations/monitor-sensu/log-sensu-systemd.md b/archived/sensu-go/6.8/operations/monitor-sensu/log-sensu-systemd.md similarity index 100% rename from content/sensu-go/6.8/operations/monitor-sensu/log-sensu-systemd.md rename to archived/sensu-go/6.8/operations/monitor-sensu/log-sensu-systemd.md diff --git a/content/sensu-go/6.8/operations/monitor-sensu/monitor-sensu-with-sensu.md b/archived/sensu-go/6.8/operations/monitor-sensu/monitor-sensu-with-sensu.md similarity index 100% rename from content/sensu-go/6.8/operations/monitor-sensu/monitor-sensu-with-sensu.md rename to archived/sensu-go/6.8/operations/monitor-sensu/monitor-sensu-with-sensu.md diff --git a/content/sensu-go/6.8/operations/monitor-sensu/ready.md b/archived/sensu-go/6.8/operations/monitor-sensu/ready.md similarity index 100% rename from content/sensu-go/6.8/operations/monitor-sensu/ready.md rename to archived/sensu-go/6.8/operations/monitor-sensu/ready.md diff --git a/content/sensu-go/6.8/operations/monitor-sensu/tessen.md b/archived/sensu-go/6.8/operations/monitor-sensu/tessen.md similarity index 100% rename from content/sensu-go/6.8/operations/monitor-sensu/tessen.md rename to archived/sensu-go/6.8/operations/monitor-sensu/tessen.md diff --git a/content/sensu-go/6.8/operations/monitoring-as-code/_index.md b/archived/sensu-go/6.8/operations/monitoring-as-code/_index.md similarity index 100% rename from content/sensu-go/6.8/operations/monitoring-as-code/_index.md rename to archived/sensu-go/6.8/operations/monitoring-as-code/_index.md diff --git a/content/sensu-go/6.8/platforms.md b/archived/sensu-go/6.8/platforms.md similarity index 100% rename from content/sensu-go/6.8/platforms.md rename to archived/sensu-go/6.8/platforms.md diff --git a/content/sensu-go/6.8/plugins/_index.md b/archived/sensu-go/6.8/plugins/_index.md similarity index 100% rename from content/sensu-go/6.8/plugins/_index.md rename to archived/sensu-go/6.8/plugins/_index.md diff --git a/content/sensu-go/6.8/plugins/assets.md b/archived/sensu-go/6.8/plugins/assets.md similarity index 100% rename from content/sensu-go/6.8/plugins/assets.md rename to archived/sensu-go/6.8/plugins/assets.md diff --git a/content/sensu-go/6.8/plugins/featured-integrations/_index.md b/archived/sensu-go/6.8/plugins/featured-integrations/_index.md similarity index 100% rename from content/sensu-go/6.8/plugins/featured-integrations/_index.md rename to archived/sensu-go/6.8/plugins/featured-integrations/_index.md diff --git a/content/sensu-go/6.8/plugins/featured-integrations/ansible.md b/archived/sensu-go/6.8/plugins/featured-integrations/ansible.md similarity index 100% rename from content/sensu-go/6.8/plugins/featured-integrations/ansible.md rename to archived/sensu-go/6.8/plugins/featured-integrations/ansible.md diff --git a/content/sensu-go/6.8/plugins/featured-integrations/aws-ec2.md b/archived/sensu-go/6.8/plugins/featured-integrations/aws-ec2.md similarity index 100% rename from content/sensu-go/6.8/plugins/featured-integrations/aws-ec2.md rename to archived/sensu-go/6.8/plugins/featured-integrations/aws-ec2.md diff --git a/content/sensu-go/6.8/plugins/featured-integrations/chef.md b/archived/sensu-go/6.8/plugins/featured-integrations/chef.md similarity index 100% rename from content/sensu-go/6.8/plugins/featured-integrations/chef.md rename to archived/sensu-go/6.8/plugins/featured-integrations/chef.md diff --git a/content/sensu-go/6.8/plugins/featured-integrations/elasticsearch.md b/archived/sensu-go/6.8/plugins/featured-integrations/elasticsearch.md similarity index 100% rename from content/sensu-go/6.8/plugins/featured-integrations/elasticsearch.md rename to archived/sensu-go/6.8/plugins/featured-integrations/elasticsearch.md diff --git a/content/sensu-go/6.8/plugins/featured-integrations/email.md b/archived/sensu-go/6.8/plugins/featured-integrations/email.md similarity index 100% rename from content/sensu-go/6.8/plugins/featured-integrations/email.md rename to archived/sensu-go/6.8/plugins/featured-integrations/email.md diff --git a/content/sensu-go/6.8/plugins/featured-integrations/graphite.md b/archived/sensu-go/6.8/plugins/featured-integrations/graphite.md similarity index 100% rename from content/sensu-go/6.8/plugins/featured-integrations/graphite.md rename to archived/sensu-go/6.8/plugins/featured-integrations/graphite.md diff --git a/content/sensu-go/6.8/plugins/featured-integrations/influxdb.md b/archived/sensu-go/6.8/plugins/featured-integrations/influxdb.md similarity index 100% rename from content/sensu-go/6.8/plugins/featured-integrations/influxdb.md rename to archived/sensu-go/6.8/plugins/featured-integrations/influxdb.md diff --git a/content/sensu-go/6.8/plugins/featured-integrations/jira.md b/archived/sensu-go/6.8/plugins/featured-integrations/jira.md similarity index 100% rename from content/sensu-go/6.8/plugins/featured-integrations/jira.md rename to archived/sensu-go/6.8/plugins/featured-integrations/jira.md diff --git a/content/sensu-go/6.8/plugins/featured-integrations/opentsdb.md b/archived/sensu-go/6.8/plugins/featured-integrations/opentsdb.md similarity index 100% rename from content/sensu-go/6.8/plugins/featured-integrations/opentsdb.md rename to archived/sensu-go/6.8/plugins/featured-integrations/opentsdb.md diff --git a/content/sensu-go/6.8/plugins/featured-integrations/pagerduty.md b/archived/sensu-go/6.8/plugins/featured-integrations/pagerduty.md similarity index 100% rename from content/sensu-go/6.8/plugins/featured-integrations/pagerduty.md rename to archived/sensu-go/6.8/plugins/featured-integrations/pagerduty.md diff --git a/content/sensu-go/6.8/plugins/featured-integrations/prometheus.md b/archived/sensu-go/6.8/plugins/featured-integrations/prometheus.md similarity index 100% rename from content/sensu-go/6.8/plugins/featured-integrations/prometheus.md rename to archived/sensu-go/6.8/plugins/featured-integrations/prometheus.md diff --git a/content/sensu-go/6.8/plugins/featured-integrations/puppet.md b/archived/sensu-go/6.8/plugins/featured-integrations/puppet.md similarity index 100% rename from content/sensu-go/6.8/plugins/featured-integrations/puppet.md rename to archived/sensu-go/6.8/plugins/featured-integrations/puppet.md diff --git a/content/sensu-go/6.8/plugins/featured-integrations/rundeck.md b/archived/sensu-go/6.8/plugins/featured-integrations/rundeck.md similarity index 100% rename from content/sensu-go/6.8/plugins/featured-integrations/rundeck.md rename to archived/sensu-go/6.8/plugins/featured-integrations/rundeck.md diff --git a/content/sensu-go/6.8/plugins/featured-integrations/saltstack.md b/archived/sensu-go/6.8/plugins/featured-integrations/saltstack.md similarity index 100% rename from content/sensu-go/6.8/plugins/featured-integrations/saltstack.md rename to archived/sensu-go/6.8/plugins/featured-integrations/saltstack.md diff --git a/content/sensu-go/6.8/plugins/featured-integrations/servicenow.md b/archived/sensu-go/6.8/plugins/featured-integrations/servicenow.md similarity index 100% rename from content/sensu-go/6.8/plugins/featured-integrations/servicenow.md rename to archived/sensu-go/6.8/plugins/featured-integrations/servicenow.md diff --git a/content/sensu-go/6.8/plugins/featured-integrations/slack.md b/archived/sensu-go/6.8/plugins/featured-integrations/slack.md similarity index 100% rename from content/sensu-go/6.8/plugins/featured-integrations/slack.md rename to archived/sensu-go/6.8/plugins/featured-integrations/slack.md diff --git a/content/sensu-go/6.8/plugins/featured-integrations/sumologic.md b/archived/sensu-go/6.8/plugins/featured-integrations/sumologic.md similarity index 100% rename from content/sensu-go/6.8/plugins/featured-integrations/sumologic.md rename to archived/sensu-go/6.8/plugins/featured-integrations/sumologic.md diff --git a/content/sensu-go/6.8/plugins/featured-integrations/timescaledb.md b/archived/sensu-go/6.8/plugins/featured-integrations/timescaledb.md similarity index 100% rename from content/sensu-go/6.8/plugins/featured-integrations/timescaledb.md rename to archived/sensu-go/6.8/plugins/featured-integrations/timescaledb.md diff --git a/content/sensu-go/6.8/plugins/featured-integrations/wavefront.md b/archived/sensu-go/6.8/plugins/featured-integrations/wavefront.md similarity index 100% rename from content/sensu-go/6.8/plugins/featured-integrations/wavefront.md rename to archived/sensu-go/6.8/plugins/featured-integrations/wavefront.md diff --git a/content/sensu-go/6.8/plugins/install-plugins.md b/archived/sensu-go/6.8/plugins/install-plugins.md similarity index 100% rename from content/sensu-go/6.8/plugins/install-plugins.md rename to archived/sensu-go/6.8/plugins/install-plugins.md diff --git a/content/sensu-go/6.8/plugins/plugins.md b/archived/sensu-go/6.8/plugins/plugins.md similarity index 100% rename from content/sensu-go/6.8/plugins/plugins.md rename to archived/sensu-go/6.8/plugins/plugins.md diff --git a/content/sensu-go/6.8/plugins/use-assets-to-install-plugins.md b/archived/sensu-go/6.8/plugins/use-assets-to-install-plugins.md similarity index 100% rename from content/sensu-go/6.8/plugins/use-assets-to-install-plugins.md rename to archived/sensu-go/6.8/plugins/use-assets-to-install-plugins.md diff --git a/content/sensu-go/6.8/reference/_index.md b/archived/sensu-go/6.8/reference/_index.md similarity index 100% rename from content/sensu-go/6.8/reference/_index.md rename to archived/sensu-go/6.8/reference/_index.md diff --git a/content/sensu-go/6.8/release-notes.md b/archived/sensu-go/6.8/release-notes.md similarity index 100% rename from content/sensu-go/6.8/release-notes.md rename to archived/sensu-go/6.8/release-notes.md diff --git a/content/sensu-go/6.8/sensu-plus.md b/archived/sensu-go/6.8/sensu-plus.md similarity index 100% rename from content/sensu-go/6.8/sensu-plus.md rename to archived/sensu-go/6.8/sensu-plus.md diff --git a/content/sensu-go/6.8/sensuctl/_index.md b/archived/sensu-go/6.8/sensuctl/_index.md similarity index 100% rename from content/sensu-go/6.8/sensuctl/_index.md rename to archived/sensu-go/6.8/sensuctl/_index.md diff --git a/content/sensu-go/6.8/sensuctl/back-up-recover.md b/archived/sensu-go/6.8/sensuctl/back-up-recover.md similarity index 100% rename from content/sensu-go/6.8/sensuctl/back-up-recover.md rename to archived/sensu-go/6.8/sensuctl/back-up-recover.md diff --git a/content/sensu-go/6.8/sensuctl/create-manage-resources.md b/archived/sensu-go/6.8/sensuctl/create-manage-resources.md similarity index 100% rename from content/sensu-go/6.8/sensuctl/create-manage-resources.md rename to archived/sensu-go/6.8/sensuctl/create-manage-resources.md diff --git a/content/sensu-go/6.8/sensuctl/environment-variables.md b/archived/sensu-go/6.8/sensuctl/environment-variables.md similarity index 100% rename from content/sensu-go/6.8/sensuctl/environment-variables.md rename to archived/sensu-go/6.8/sensuctl/environment-variables.md diff --git a/content/sensu-go/6.8/sensuctl/filter-responses.md b/archived/sensu-go/6.8/sensuctl/filter-responses.md similarity index 100% rename from content/sensu-go/6.8/sensuctl/filter-responses.md rename to archived/sensu-go/6.8/sensuctl/filter-responses.md diff --git a/content/sensu-go/6.8/sensuctl/sensuctl-bonsai.md b/archived/sensu-go/6.8/sensuctl/sensuctl-bonsai.md similarity index 100% rename from content/sensu-go/6.8/sensuctl/sensuctl-bonsai.md rename to archived/sensu-go/6.8/sensuctl/sensuctl-bonsai.md diff --git a/content/sensu-go/6.8/versions.md b/archived/sensu-go/6.8/versions.md similarity index 100% rename from content/sensu-go/6.8/versions.md rename to archived/sensu-go/6.8/versions.md diff --git a/content/sensu-go/6.8/web-ui/_index.md b/archived/sensu-go/6.8/web-ui/_index.md similarity index 100% rename from content/sensu-go/6.8/web-ui/_index.md rename to archived/sensu-go/6.8/web-ui/_index.md diff --git a/content/sensu-go/6.8/web-ui/bsm-module.md b/archived/sensu-go/6.8/web-ui/bsm-module.md similarity index 100% rename from content/sensu-go/6.8/web-ui/bsm-module.md rename to archived/sensu-go/6.8/web-ui/bsm-module.md diff --git a/content/sensu-go/6.8/web-ui/search.md b/archived/sensu-go/6.8/web-ui/search.md similarity index 100% rename from content/sensu-go/6.8/web-ui/search.md rename to archived/sensu-go/6.8/web-ui/search.md diff --git a/content/sensu-go/6.8/web-ui/searches-reference.md b/archived/sensu-go/6.8/web-ui/searches-reference.md similarity index 100% rename from content/sensu-go/6.8/web-ui/searches-reference.md rename to archived/sensu-go/6.8/web-ui/searches-reference.md diff --git a/content/sensu-go/6.8/web-ui/view-manage-resources.md b/archived/sensu-go/6.8/web-ui/view-manage-resources.md similarity index 100% rename from content/sensu-go/6.8/web-ui/view-manage-resources.md rename to archived/sensu-go/6.8/web-ui/view-manage-resources.md diff --git a/content/sensu-go/6.8/web-ui/webconfig-reference.md b/archived/sensu-go/6.8/web-ui/webconfig-reference.md similarity index 100% rename from content/sensu-go/6.8/web-ui/webconfig-reference.md rename to archived/sensu-go/6.8/web-ui/webconfig-reference.md diff --git a/content/sensu-go/6.8/web-ui/webconfig.md b/archived/sensu-go/6.8/web-ui/webconfig.md similarity index 100% rename from content/sensu-go/6.8/web-ui/webconfig.md rename to archived/sensu-go/6.8/web-ui/webconfig.md diff --git a/config.toml b/config.toml index 4c06bf3ef9..81584bf960 100755 --- a/config.toml +++ b/config.toml @@ -56,22 +56,22 @@ disableKinds = ["taxonomy", "taxonomyTerm"] description = "The next-generation monitoring event pipeline" notice = "Replaces Sensu Core and Enterprise" weight = 1 - latest = "6.11" + latest = "6.12" [[params.products.sensu_go.versions]] - version = "6.11" + version = "6.12" platforms = [] [[params.products.sensu_go.versions]] - version = "6.10" + version = "6.11" platforms = [] [[params.products.sensu_go.versions]] - version = "6.9" + version = "6.10" platforms = [] [[params.products.sensu_go.versions]] - version = "6.8" + version = "6.9" platforms = [] [params.products.sensu_core] diff --git a/content/sensu-go/6.12/_index.md b/content/sensu-go/6.12/_index.md new file mode 100644 index 0000000000..3e644b9acb --- /dev/null +++ b/content/sensu-go/6.12/_index.md @@ -0,0 +1,111 @@ +--- +title: "Sensu Go" +description: "Sensu is the operator-focused, developer-friendly, industry-leading solution for multi-cloud monitoring and observability at scale." +weight: -100 +menu: "sensu-go-6.12" +version: "6.12" +product: "Sensu Go" +layout: "single" +--- + + Learn about licensing + +[Sensu][25] is a complete solution for monitoring and observability at scale. +Sensu Go is designed to give you visibility into everything you care about: traditional server closets, containers, applications, the cloud, and more. + +** or click any element in the Sensu observability pipeline to jump to it.** + + + + +Sensu is an [agent-based][26] observability tool that you install on your organization's infrastructure. +The Sensu [backend][27] gives you a flexible, automated pipeline to filter, transform, and process alerts and metrics. + +Sensu Go is [operator-focused][11] and [developer-friendly][20] and [integrates][7] with popular monitoring and observability tools. +Deploy Sensu Go for on-premises and public cloud infrastructures, containers, bare metal, or any other environment. + +**[Get started now][1] and feel the #monitoringlove**. + +## Filtered, context-rich alerts that improve incident response + +Get meaningful alerts when and where you need them so you can [reduce alert fatigue][28] and [speed up incident response][29]. +Sensu gives you full control over your alerts with flexible [event filters][8], [check hooks][9] for context-rich notifications, reporting, [observation data handling][24], and auto-remediation. + +## Extend functionality and integrate with existing workflows with the Sensu Catalog + +Use the [Sensu Catalog][41], the online marketplace for monitoring and observability integrations, to find and install integrations directly in your browser. + +Sensu's open architecture integrates with the tools and services you already use, like Ansible, Amazon EC2, InfluxDB, Kubernetes, PagerDuty, Saltstack, and Sumo Logic. +The Sensu Catalog also includes standard system checks and metrics collectors. + +To start integrating Sensu with your existing workflows, read the [Sensu Catalog][41] documentation, check out our [featured integrations][38], search for plugins in [Bonsai, the Sensu asset hub][18], or write your own [Sensu plugins][3] in any language. + +## Automate with agent registration-deregistration and check subscriptions + +Sensu [agents][26] automatically [register and deregister][21] themselves with the Sensu backend so you can collect observation data about ephemeral infrastructure without getting overloaded with alerts. + +Instead of [setting up][30] traditional one-to-one entity-to-check mapping, use Sensu's [subscriptions][39] to make sure your entities automatically run the appropriate checks for their functionality. + +## Built-in support for industry-standard tools + +Know what's going on everywhere in your system. +Sensu supports [industry-standard metric formats][10] like Nagios performance data, Graphite plaintext protocol, InfluxDB line protocol, OpenTSDB data specification, Prometheus Exposition Text Format, and [StatsD metrics][14]. +Use the Sensu agent to [collect metrics][40] alongside check results, then use the Sensu observability pipeline to route observation data to a time-series database like [InfluxDB][2]. + +## Intuitive API with command line and web interfaces + +The [Sensu API][13] and the [`sensuctl` command-line tool][16] allow you (and your internal customers) to create checks, register entities, manage configuration, and more. +The Sensu [web UI][15] provides a unified view of your entities, checks, and events, as well as a user-friendly [silencing][31] tool. + +## Commercial software based on open core + +Sensu Go is a commercial product, based on an open source core that is freely available under a permissive [MIT License][4] and publicly available on [GitHub][5]. +Learn about our commercial [support packages][22] and [features designed for observability at scale][12]. + +Sensu Go is the latest version of Sensu, designed to be portable, straightforward to deploy, and friendly to containerized and ephemeral environments. +Sensu Inc. released Sensu Go OSS as open source in 2017, and it is now a part of Sumo Logic Inc. (SUMO). + +Sensu is a comprehensive monitoring and observability solution for enterprises, providing complete visibility across every system, every protocol, every time — from Kubernetes to bare metal. + + +[1]: get-started/ +[2]: observability-pipeline/observe-process/populate-metrics-influxdb/ +[3]: plugins/ +[4]: https://www.github.com/sensu/sensu-go/blob/main/LICENSE/ +[5]: https://www.github.com/sensu/sensu-go/ +[6]: operations/deploy-sensu/cluster-sensu/ +[7]: #built-in-support-for-industry-standard-tools +[8]: observability-pipeline/observe-filter/filters/ +[9]: observability-pipeline/observe-schedule/hooks/ +[10]: observability-pipeline/observe-schedule/metrics/#supported-output-metric-formats +[11]: #intuitive-api-with-command-line-and-web-interfaces +[12]: commercial/ +[13]: api/ +[14]: observability-pipeline/observe-process/aggregate-metrics-statsd/ +[15]: web-ui/ +[16]: sensuctl/ +[17]: plugins/featured-integrations/slack/ +[18]: https://bonsai.sensu.io/ +[19]: plugins/featured-integrations/pagerduty/ +[20]: #filtered-context-rich-alerts-that-improve-incident-response +[21]: observability-pipeline/observe-schedule/agent/#registration-events +[22]: https://sensu.io/support +[23]: plugins/featured-integrations/puppet/ +[24]: observability-pipeline/observe-process/handlers/ +[25]: operations/deploy-sensu/install-sensu/ +[26]: observability-pipeline/observe-schedule/agent/ +[27]: observability-pipeline/observe-schedule/backend/ +[28]: observability-pipeline/observe-filter/reduce-alert-fatigue/ +[29]: observability-pipeline/observe-filter/route-alerts/ +[30]: operations/deploy-sensu/ +[31]: web-ui/view-manage-resources/ +[32]: plugins/featured-integrations/influxdb/ +[33]: plugins/featured-integrations/ansible/ +[34]: plugins/featured-integrations/sumologic/ +[35]: plugins/featured-integrations/aws-ec2/ +[36]: plugins/featured-integrations/rundeck/ +[37]: plugins/featured-integrations/saltstack/ +[38]: plugins/featured-integrations/ +[39]: observability-pipeline/observe-schedule/subscriptions/ +[40]: observability-pipeline/observe-schedule/collect-metrics-with-checks/ +[41]: catalog/sensu-catalog/ diff --git a/content/sensu-go/6.12/api/_index.md b/content/sensu-go/6.12/api/_index.md new file mode 100644 index 0000000000..9261b2d6a7 --- /dev/null +++ b/content/sensu-go/6.12/api/_index.md @@ -0,0 +1,817 @@ +--- +title: "API" +description: "Sensu's backend API provides a centrally managed control plane for automated, repeatable observability workflow configuration and observation event access." +weight: 60 +product: "Sensu Go" +version: "6.12" +layout: "single" +menu: + sensu-go-6.12: + identifier: api +--- + +**API version: v2** + +The Sensu backend REST API provides a centrally managed control plane for automated, repeatable monitoring and observability workflow configuration and observation event data access. + +If you have a healthy [clustered][24] backend, you only need to make Sensu API calls to any one of the cluster members. +The cluster protocol will replicate your changes to all cluster members. + +For information about the Sensu agent API, read the [agent reference][4]. + +## Available APIs + +Access all of the data and functionality of Sensu's first-class API clients, [sensuctl][25] and the [web UI][26], with Sensu's backend REST APIs. +Use the Sensu APIs and endpoints to customize your workflows and integrate your favorite Sensu features with other tools and products. + +### core/v2 API endpoints + +The core/v2 API includes endpoints for the following Sensu resources: + +{{< coreapiListing >}} + +### Enterprise APIs + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access Sensu's enterprise APIs in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../commercial/). +{{% /notice %}} + +The enterprise APIs include: + +{{< enterpriseapiListing >}} + +### Other endpoints + +Sensu offers additional endpoints for basic authentication, health, license, metrics, and version: + +{{< otherapiListing >}} + +## URL format + +Most core/v2 API endpoints use the standard URL format `/api/core//namespaces/` where: + +- `` is the API version: `v2`. +- `` is the namespace name. + +For enterprise APIs for [namespaced resources][32], the URL format also includes a group that indicates the relevant enterprise feature: +`/api/enterprise///namespaces/`. + +For enterprise APIs for [cluster-wide resources][33], the URL format does not include namespace elements: +`/api/enterprise//`. + +The [endpoint-only APIs][34] do not follow a standard URL format. + +### Namespaces in API URLs + +The examples in the API documentation use the `default` namespace. + +The Sensu API requires the authenticated user to have the correct access permissions for the namespace specified in the URL. +If the authenticated user has the correct cluster-wide permissions, you can leave out the `/namespaces/` portion of the URL to access Sensu resources across namespaces. + +Read the [RBAC reference][3] for more information about configuring Sensu users and access controls. + +## Data format + +The Sensu API uses JSON-formatted requests and responses. + +In terms of output formats, the [Sensu API][9] uses `json` output format for responses for APIs in the [`core` group][29]. +For APIs that are not in the `core` group, responses are in the `wrapped-json` output format. +The `wrapped-json` format includes an outer-level `spec` "wrapping" for resource attributes and lists the resource `type` and `api_version`. + +Sensu sends events to the backend in [`json` format][28], without the `spec` attribute wrapper or `type` and `api_version` attributes. + +## Versioning + +The Sensu Go API is versioned according to the format `v{majorVersion}{stabilityLevel}{iterationNumber}`, in which `v2` is stable version 2. +The Sensu API guarantees backward compatibility for stable versions of the API. + +Sensu does not guarantee that an alpha or beta API will be maintained for any period of time. +Consider alpha versions under active development — they may not be published for every release. +Beta APIs are more stable than alpha versions, but they offer similarly short-lived lifespans and also are not guaranteed to convert programmatically when the API is updated. + +## Request size limit + +The default limit for API request body size is 0.512 MB. +Use the [`api-request-limit` backend configuration option][21] to customize the API request body size limit if needed. + +## Access control + +With the exception of the [authentication][12], [health][5], [metrics][6], [ready][30], and [version][31] API endpoints, the Sensu API requires authentication using a [JSON Web Token][27] (JWT) [access token][20] or [API key][17]. + +Code examples in the Sensu API docs use the environment variable `$SENSU_API_KEY` to represent a valid API key in API requests. + +{{% notice note %}} +**NOTE**: The authentication information on this page is specific to the Sensu API. +For information about using Sensu's built-in basic authentication or external authentication providers to authenticate to the Sensu web UI, API, or sensuctl, read the [Control Access](../operations/control-access) documentation. +{{% /notice %}} + +### Authentication quickstart + +To set up a local API testing environment, save your Sensu credentials and access token as environment variables. + +Save your Sensu credentials as environment variables: + +{{< code shell >}} +export SENSU_USER=YOUR_USERNAME && SENSU_PASS=YOUR_PASSWORD +{{< /code >}} + +Save your Sensu access token as an environment variable: + +{{% notice note %}} +**NOTE**: The command to save your access token as an environment variable requires curl and jq. +{{% /notice %}} + +{{< code shell >}} +export SENSU_ACCESS_TOKEN=`curl -X GET -u "$SENSU_USER:$SENSU_PASS" -s http://localhost:8080/auth | jq -r ".access_token"` +{{< /code >}} + +The [sensuctl reference][7] demonstrates how to use the `sensuctl env` command to export your access token, token expiry time, and refresh token as environment variables. + +### Authenticate with /auth API endpoints + +Use the [authentication API][12] and your Sensu username and password to generate access tokens and refresh tokens. +The [`/auth` API endpoint][12] lets you generate short-lived API tokens using your Sensu username and password. + +1. Retrieve an access token for your user. +For example, to generate an access token using example admin credentials: +{{< code shell >}} +curl -u 'YOUR_USERNAME:YOUR_PASSWORD' http://localhost:8080/auth +{{< /code >}} +The access token should be included in the output, along with a refresh token: +{{< code shell >}} +{ + "access_token": "eyJhbGciOiJIUzI1NiIs...", + "expires_at": 1544582187, + "refresh_token": "eyJhbGciOiJIUzI1NiIs..." +} +{{< /code >}} +The access and refresh tokens are [JWTs][2] that Sensu uses to digitally sign the details of users' authenticated Sensu sessions. + +2. Use the access token in the authentication header of the API request. +For example: +{{< code shell >}} +curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/events +{{< /code >}} + +3. Refresh your access token every 15 minutes. +Access tokens last for approximately 15 minutes. +When your token expires, you should receive a `401 Unauthorized` response from the API. +To generate a new access token, use the [`/auth/token` API endpoint][11], including the expired access token in the authorization header and the refresh token in the request body: +{{< code shell >}} +curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \ +-H 'Content-Type: application/json' \ +-d '{"refresh_token": "eyJhbGciOiJIUzI1NiIs..."}' \ +http://127.0.0.1:8080/auth/token +{{< /code >}} +The new access token should be included in the output: +{{< code shell >}} +{ + "access_token": "eyJhbGciOiJIUzI1NiIs...", + "expires_at": 1561055277, + "refresh_token": "eyJhbGciOiJIUzI1NiIs..." +} +{{< /code >}} + +### Generate an API access token with sensuctl + +You can also generate an API access token using the sensuctl command line tool. +The user credentials that you use to configure sensuctl determine your permissions to get, list, create, update, and delete resources with the Sensu API. + +1. [Install and configure sensuctl][2]. + +2. Retrieve an access token for your user: +{{< code shell >}} +cat ~/.config/sensu/sensuctl/cluster|grep access_token +{{< /code >}} +The access token should be included in the output: +{{< code shell >}} +"access_token": "eyJhbGciOiJIUzI1NiIs...", +{{< /code >}} + +3. Copy the access token into the authentication header of the API request. +For example: +{{< code shell >}} +curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/events +{{< /code >}} + +4. Refresh your access token every 15 minutes. +Access tokens last for approximately 15 minutes. +When your token expires, you should receive a `401 Unauthorized` response from the API. +To regenerate a valid access token, run any sensuctl command (like `sensuctl event list`) and repeat step 2. + +### Authenticate with an API key + +Each Sensu API key ([core/v2/apikey][19]) is a persistent universally unique identifier (UUID) that maps to a stored Sensu username. +The advantages of authenticating with API keys rather than [access tokens][14] include: + +- **More efficient integration**: Check and handler plugins and other code can integrate with the Sensu API without implementing the logic required to authenticate via the `/auth` API endpoint to periodically refresh the access token +- **Improved security**: API keys do not require providing a username and password in check or handler definitions +- **Better admin control**: API keys can be created and revoked without changing the underlying user's password, but keep in mind that API keys will continue to work even if the user's password changes + +API keys are cluster-wide resources, so only cluster admins can grant, view, and revoke them. + +{{% notice note %}} +**NOTE**: API keys are not supported for authentication providers such as LDAP and OIDC. +{{% /notice %}} + +#### Configure an environment variable for API key authentication + +Configure the `SENSU_API_KEY` environment variable with your own API key to use it for authentication in your Sensu API requests as shown in the Sensu API code examples. + +Follow these steps to generate an API key and export it to the `SENSU_API_KEY` environment variable: + +1. Generate an API key with [sensuctl][18]: +{{< code shell >}} +sensuctl api-key grant admin +{{< /code >}} + + The response will include the new API key: +{{< code text >}} +Created: /api/core/v2/apikeys/83abef1e-e7d7-4beb-91fc-79ad90084d5b +{{< /code >}} + + {{% notice protip %}} +**PRO TIP**: Sensuctl is the most direct way to generate an API key, but you can also use the [POST core/v2/apikeys endpoint](core/apikeys/#create-a-new-api-key). +{{% /notice %}} + +2. Export your API key to the `SENSU_API_KEY` environment variable: +{{< language-toggle >}} + +{{< code bash >}} +export SENSU_API_KEY="83abef1e-e7d7-4beb-91fc-79ad90084d5b" +{{< /code >}} + +{{< code cmd >}} +SET SENSU_API_KEY="83abef1e-e7d7-4beb-91fc-79ad90084d5b" +{{< /code >}} + +{{< code powershell >}} +$Env:SENSU_API_KEY = "83abef1e-e7d7-4beb-91fc-79ad90084d5b" +{{< /code >}} + +{{< /language-toggle >}} + +#### Authorization header for API key authentication + +Similar to the `Bearer [token]` Authorization header, `Key [api-key]` will be accepted as an Authorization header for authentication. + +For example, a JWT `Bearer [token]` Authorization header might be: + +{{< code shell >}} +curl -H "Authorization: Bearer $SENSU_ACCESS_TOKEN" http://127.0.0.1:8080/api/core/v2/namespaces/default/checks +{{< /code >}} + +If you're using `Key [api-key]` to authenticate instead, the Authorization header might be: + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/namespaces/default/checks +{{< /code >}} + +### Example + +This example uses the API key directly (rather than the `$SENSU_API_KEY` environment variable) to authenticate to core/v2/checks: + +{{< code shell >}} +curl -H "Authorization: Key 7f63b5bc-41f4-4b3e-b59b-5431afd7e6a2" http://127.0.0.1:8080/api/core/v2/namespaces/default/checks +{{< /code >}} + +A successful request will return the HTTP response code `HTTP/1.1 200 OK` and the definitions for the checks in the default namespace. + +## Pagination + +The Sensu API supports response pagination for most core/v2 GET endpoints that return an array. +You can request a paginated response with the `limit` and `continue` query parameters. + +### Limit query parameter + +The following request limits the response to a maximum of two objects: + +{{< code shell >}} +curl http://127.0.0.1:8080/api/core/v2/users?limit=2 -H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The response includes the available objects up to the specified limit. + +### Continue query parameter + +If more objects are available beyond the [limit][16] you specified in a request, the response header includes a `Sensu-Continue` token you can use to request the next page of objects. + +For example, the following response indicates that more than two users are available because it provides a `Sensu-Continue` token in the response header: + +{{< code shell >}} +HTTP/1.1 200 OK +Content-Type: application/json +Sensu-Continue: L2RlZmF1bU2Vuc3UtTWFjQ +Sensu-Entity-Count: 3 +Sensu-Entity-Limit: 100 +Sensu-Entity-Warning: +Date: Fri, 14 Feb 2020 15:44:25 GMT +Content-Length: 132 +[ + { + "username": "alice", + "groups": [ + "ops" + ], + "disabled": false + }, + { + "username": "bob", + "groups": [ + "ops" + ], + "disabled": false + } +] +{{< /code >}} + +To request the next two available users, use the `Sensu-Continue` token included in the response header: + +{{< code shell >}} +curl http://127.0.0.1:8080/api/core/v2/users?limit=2&continue=L2RlZmF1bU2Vuc3UtTWFjQ \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +If the response header does not include a `Sensu-Continue` token, there are no further objects to return. +For example, this response header indicates that no further users are available: + +{{< code shell >}} +HTTP/1.1 200 OK +Content-Type: application/json +Sensu-Entity-Count: 3 +Sensu-Entity-Limit: 100 +Sensu-Entity-Warning: +Date: Fri, 14 Feb 2020 15:46:02 GMT +Content-Length: 54 +[ + { + "username": "alice", + "groups": [ + "ops" + ], + "disabled": false + } +] +{{< /code >}} + +## Etag response headers + +All GET and PATCH requests return an [Etag HTTP response header][10] that identifies a specific version of the resource. +Use the Etag value from the response header to conditionally execute PATCH requests that use the [If-Match][22] and [If-None-Match][23] headers. + +If Sensu cannot execute a PATCH request because one of the conditions failed, the request will return the HTTP response code `412 Precondition Failed`. + +### If-Match example + +{{< code shell >}} +curl -X PATCH \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/merge-patch+json' \ +-H 'If-Match: "drrn157624731797"' \ +-d '{ + "metadata": { + "labels": { + "region": "us-west-1" + } + } +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/assets/sensu-slack-handler +{{< /code >}} + +A successful request will return the HTTP response code `HTTP/1.1 200 OK`. + +### If-None-Match example + +{{< code shell >}} +curl -X PATCH \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/merge-patch+json' \ +-H 'If-None-Match: "drrn157624731797", "reew237527931897"' \ +-d '{ + "metadata": { + "labels": { + "region": "us-west-1" + } + } +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/assets/sensu-slack-handler +{{< /code >}} + +A successful request will return the HTTP response code `HTTP/1.1 200 OK`. + +## Response filtering + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access API response filtering in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../commercial/). +{{% /notice %}} + +The Sensu API supports response filtering for all GET endpoints that return an array. +You can filter resources based on their labels with the `labelSelector` query parameter and based on certain pre-determined fields with the `fieldSelector` query parameter. + +{{% notice note %}} +**NOTE**: To search based on fields and labels in the Sensu web UI, read [Search in the web UI](../web-ui/search/). +{{% /notice %}} + +### Label selector + +The `labelSelector` query parameter allows you to group resources by the label attributes specified in the resource metadata object. +All resources support labels within the [metadata object][9]. + +### Field selector + +The `fieldSelector` query parameter allows you to organize and select subsets of resources based on certain fields. +Here's the list of available fields: + +| Resource | Fields | +| ----------- | ----------- | +| Asset | `asset.name` `asset.namespace` `asset.filters` | +| Check | `check.name` `check.namespace` `check.handlers` `check.publish` `check.round_robin` `check.runtime_assets` `check.subscriptions`| +| ClusterRole | `clusterrole.name` | +| ClusterRoleBinding | `clusterrolebinding.name` `clusterrolebinding.role_ref.name` `clusterrolebinding.role_ref.type`| +| Entity | `entity.name` `entity.namespace` `entity.deregister` `entity.entity_class` `entity.subscriptions` | +| Event | `event.name` `event.namespace` `event.is_silenced` `event.check.handlers` `event.check.is_silenced` `event.check.name` `event.check.publish` `event.check.round_robin` `event.check.runtime_assets` `event.check.state` `event.check.status` `event.check.subscriptions` `event.entity.deregister` `event.entity.entity_class` `event.entity.name` `event.entity.subscriptions` | +| Extension | `extension.name` `extension.namespace` | +| Filter | `filter.name` `filter.namespace` `filter.action` `filter.runtime_assets` | +| Handler | `handler.name` `handler.namespace` `handler.filters` `handler.handlers` `handler.mutator` `handler.type`| +| Hook | `hook.name` `hook.namespace` | +| Mutator | `mutator.name` `mutator.namespace` `mutator.runtime_assets` | +| Namespace | `namespace.name` | +| Pipeline | `pipeline.name` `pipeline.namespace` +| Role | `role.name` `role.namespace` | +| RoleBinding | `rolebinding.name` `rolebinding.namespace` `rolebinding.role_ref.name` `rolebinding.role_ref.type`| +| Secrets | `secret.name` `secret.namespace` `secret.provider` `secret.id` | +| SecretsProviders | `provider.name` | +| Silenced | `silenced.name` `silenced.namespace` `silenced.check` `silenced.creator` `silenced.expire_on_resolve` `silenced.subscription` | +| User | `user.username` `user.disabled` `user.groups` | + +### API-specific syntax + +To create an API response filter, you'll write a brief filter statement. +The [operators][13] and [examples][15] sections demonstrate how to construct API response filter statements for different operators and specific purposes. + +The filter statement construction is slightly different for different operators, but there are a few general syntax rules that apply to all filter statements. + +#### Spaces in the filter statement + +As shown in this example: + +{{< code text >}} +'fieldSelector=silenced.expire_on_resolve == true' +{{< /code >}} + +- **Do not** use spaces around the `=` between the selector type and the rest of the filter statement. +- **Do** use spaces around the operator (in this example, the `==`). + +#### Quotation marks around the filter statement + +Place the entire filter statement inside single quotes: + +{{< code text >}} +'fieldSelector=linux in check.subscriptions' +{{< /code >}} + +**Exception**: If the filter statement contains a *shell* variable, you must use double quotation marks around the statement: + +{{< code text >}} +"labelSelector=host == $HOSTNAME" +{{< /code >}} + +If you use single quotes around a filter statement that contains a shell variable, the single quotes will keep the variable intact instead of expanding it. + +{{% notice note %}} +**NOTE**: This exception only applies to shell variables. +It does not apply for variables in languages that treat single and double quotation marks interchangeably, like JavaScript. +{{% /notice %}} + +### Values that begin with a number or include special characters + +If you are filtering for a value that begins with a number, place the value in double quotes: + +{{< code text >}} +'fieldSelector=entity.name == "1b04994n"' +{{< /code >}} + +Likewise, to use a label or field selector with string values that include special characters like hyphens and underscores, place the value in double quotes: + +{{< code text >}} +'labelSelector:region == "us-west-1"' +{{< /code >}} + +### Filter operators + +Sensu's API response filtering supports two equality-based operators, two set-based operators, one substring matching operator, and one logical operator. + +| operator | description | example | +| --------- | ------------------ | ---------------------- | +| `==` | Equality | `check.publish == true` +| `!=` | Inequality | `check.namespace != "default"` +| `in` | Included in | `linux in check.subscriptions` +| `notin` | Not included in | `slack notin check.handlers` +| `matches` | Substring matching | `check.name matches "linux-"` +| `&&` | Logical AND | `check.publish == true && slack in check.handlers` + +#### Equality-based operators + +Sensu's two _equality-based_ operators are `==` (equality) and `!=` (inequality). + +For example, to retrieve only checks with the label `type` and value `server`: + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/checks -G \ +--data-urlencode 'labelSelector=type == "server"' +{{< /code >}} + +{{% notice note %}} +**NOTE**: Use the flag `--data-urlencode` in cURL to encode the query parameter. +Include the `-G` flag so the request appends the query parameter data to the URL. +{{% /notice %}} + +To retrieve checks that are not in the `production` namespace: + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/checks -G \ +--data-urlencode 'fieldSelector=check.namespace != "production"' +{{< /code >}} + +#### Set-based operators + +Sensu's two *set-based* operators for lists of values are `in` and `notin`. + +For example, to retrieve checks with a `linux` subscription: + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/checks -G \ +--data-urlencode 'fieldSelector=linux in check.subscriptions' +{{< /code >}} + +To retrieve checks that do not use the `slack` handler: + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/checks -G \ +--data-urlencode 'fieldSelector=slack notin check.handlers' +{{< /code >}} + +The `in` and `notin` operators have two important conditions: + +- First, they only work when the underlying value you're filtering for is a string. +You can filter for strings and arrays of strings with `in` and `notin` operators, but you cannot use them to filter for integer, float, array, or Boolean values. +- Second, to filter for a string, the string must be to the **left** of the operator: `string [in|notin] selector`. +To filter for an array of strings, the array must be to the **right** of the operator: `selector [in|notin] [string1,string2]`. + +#### Substring matching operator + +Sensu's _substring matching_ operator is `matches`. + +For example, to retrieve all checks whose name includes `linux`: + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/checks -G \ +--data-urlencode 'fieldSelector=check.name matches "linux"' +{{< /code >}} + +Suppose you are using Sensu to monitor 1000 entities that are named incrementally and according to technology. +For example, your webservers are named `webserver-1` through `webserver-25`, and your CPU entities are named `cpu-1` through `cpu-300`, and so on. +In this case, you can use `matches` to retrieve all of your `webserver` entities: + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/entities -G \ +--data-urlencode 'fieldSelector=entity.name matches "webserver-"' +{{< /code >}} + +Similarly, if you have entities labeled for different regions, you can use `matches` to find the entities that are labeled for the US (for example, `us-east-1`, `us-west-1`, and so on): + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/entities -G \ +--data-urlencode 'labelSelector:region matches "us"' +{{< /code >}} + +The `matches` operator only works when the underlying value you're filtering for is a string. +You can filter for strings and arrays of strings with the `matches` operator, but you cannot use it to filter for integer, float, array, or Boolean values. +Also, the string must be to the **right** of the operator: `selector matches string`. + +#### Logical operator + +Sensu's logical operator is `&&` (AND). +Use it to combine multiple statements separated with the logical operator in field and label selectors. + +For example, the following cURL request retrieves checks that are not configured to be published **and** include the `linux` subscription: + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/checks -G \ +--data-urlencode 'fieldSelector=check.publish != true && linux in check.subscriptions' +{{< /code >}} + +To retrieve checks that are not published, include a `linux` subscription, and are in the `dev` namespace: + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/checks -G \ +--data-urlencode 'fieldSelector=check.publish != true && linux in check.subscriptions && dev in check.namespace' +{{< /code >}} + +{{% notice note %}} +**NOTE**: Sensu does not have the `OR` logical operator. +{{% /notice %}} + +### Combined selectors + +You can use field and label selectors in a single request. +For example, to retrieve only checks that include a `linux` subscription *and* do not include a label for type `server`: + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/checks -G \ +--data-urlencode 'fieldSelector=linux in check.subscriptions' \ +--data-urlencode 'labelSelector=type != "server"' +{{< /code >}} + +### Examples + +#### Values with special characters + +To use a label or field selector with string values that include special characters like hyphens and underscores, place the value in single or double quotes: + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" -X GET http://127.0.0.1:8080/api/core/v2/entities -G \ +--data-urlencode 'labelSelector=region == "us-west-1"' +{{< /code >}} + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/entities -G \ +--data-urlencode 'fieldSelector="entity:i-0c1f8a116b84ea50c" in entity.subscriptions' +{{< /code >}} + +#### Use selectors with arrays of strings + +To retrieve checks that are in either the `dev` or `production` namespace: + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/checks -G \ +--data-urlencode 'fieldSelector=check.namespace in [dev,production]' +{{< /code >}} + +#### Filter events by entity or check + +To retrieve events for a specific check (`checkhttp`): + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/events -G \ +--data-urlencode 'fieldSelector=checkhttp in event.check.name' +{{< /code >}} + +Similary, to retrieve only events for the `server` entity: + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/events -G \ +--data-urlencode 'fieldSelector=server in event.entity.name' +{{< /code >}} + +#### Filter events by severity + +Use the `event.check.status` field selector to retrieve events by severity. +For example, to retrieve all events at `2` (CRITICAL) status: + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/events -G \ +--data-urlencode 'fieldSelector=event.check.status == "2"' +{{< /code >}} + +#### Filter all incidents + +To retrieve all incidents (all events whose status is not `0`): + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/events -G \ +--data-urlencode 'fieldSelector=event.entity.status != "0"' +{{< /code >}} + +#### Filter checks, entities, or events by subscription + +To list all checks that include the `linux` subscription: + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/checks -G \ +--data-urlencode 'fieldSelector=linux in check.subscriptions' +{{< /code >}} + +Similarly, to list all entities that include the `linux` subscription: + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/entities -G \ +--data-urlencode 'fieldSelector=linux in entity.subscriptions' +{{< /code >}} + +To list all events for the `linux` subscription, use the `event.entity.subscriptions` field selector: + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/events -G \ +--data-urlencode 'fieldSelector=linux in event.entity.subscriptions' +{{< /code >}} + +#### Filter silenced resources and silences + +**Filter silenced resources by namespace** + +To list all silenced resources for a particular namespace (in this example, the `default` namespace): + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/silenced -G \ +--data-urlencode 'fieldSelector=silenced.namespace == "default"' +{{< /code >}} + +Likewise, to list all silenced resources *except* those in the `default` namespace: + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/silenced -G \ +--data-urlencode 'fieldSelector=silenced.namespace != "default"' +{{< /code >}} + +To list all silenced events for all namespaces: + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/events -G \ +--data-urlencode 'fieldSelector=event.is_silenced == true' +{{< /code >}} + +**Filter silences by creator** + +To list all silences created by the user `alice`: + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/silenced -G \ +--data-urlencode 'fieldSelector=silenced.creator == "alice"' +{{< /code >}} + +To list all silences that were not created by the `admin` user: + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/silenced -G \ +--data-urlencode 'fieldSelector=silenced.creator != "admin"' +{{< /code >}} + +**Filter silences by silence subscription** + +To retrieve silences with a specific subscription (in this example, `linux`): + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/silenced -G \ +--data-urlencode 'fieldSelector=silenced.subscription == "linux"' +{{< /code >}} + +Another way to make the same request is: + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/silenced -G \ +--data-urlencode 'fieldSelector=linux in silenced.subscription' +{{< /code >}} + +{{% notice note %}} +**NOTE**: For this field selector, `subscription` means the subscription specified for the silence. +In other words, this filter retrieves **silences** with a particular subscription, not silenced entities or checks with a matching subscription. +{{% /notice %}} + +**Filter silenced resources by expiration** + +To list all silenced resources that expire only when a matching check resolves: + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/silenced -G \ +--data-urlencode 'fieldSelector=silenced.expire_on_resolve == true' +{{< /code >}} + + +[1]: ../sensuctl/#preferred-output-format +[2]: ../operations/deploy-sensu/install-sensu#install-sensuctl +[3]: ../operations/control-access/rbac/ +[4]: ../observability-pipeline/observe-schedule/agent/ +[5]: other/health/ +[6]: other/metrics/ +[7]: ../sensuctl/environment-variables/#export-environment-variables-with-sensuctl-env +[9]: ../observability-pipeline/observe-entities/entities#metadata-attributes +[10]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag +[11]: other/auth/#authtoken-post +[12]: other/auth/ +[13]: #filter-operators +[14]: #authentication-quickstart +[15]: #examples +[16]: #limit-query-parameter +[17]: #authenticate-with-an-api-key +[18]: ../operations/control-access/use-apikeys/#sensuctl-management-commands +[19]: core/apikeys/ +[20]: #authenticate-with-auth-api-endpoints +[21]: ../observability-pipeline/observe-schedule/backend/#api-request-limit +[22]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Match +[23]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-None-Match +[24]: ../operations/deploy-sensu/cluster-sensu/ +[25]: ../sensuctl/ +[26]: ../web-ui/ +[27]: https://tools.ietf.org/html/rfc7519 +[28]: ../observability-pipeline/observe-events/events/#example-status-only-event-from-the-sensu-api +[29]: core/ +[30]: other/ready/ +[31]: other/version/ +[32]: ../operations/control-access/rbac/#namespaced-resource-types +[33]: ../operations/control-access/rbac/#cluster-wide-resource-types +[34]: other/ diff --git a/content/sensu-go/6.12/api/core/_index.md b/content/sensu-go/6.12/api/core/_index.md new file mode 100644 index 0000000000..c504ef3288 --- /dev/null +++ b/content/sensu-go/6.12/api/core/_index.md @@ -0,0 +1,18 @@ +--- +title: "Core API" +description: "Use the Sensu core/v2 API to customize your workflows, integrate Sensu with other tools and products, and get HTTP access to your Sensu events and resources." +product: "Sensu Go" +version: "6.12" +weight: 20 +layout: "single" +toc: false +menu: + sensu-go-6.12: + parent: api + identifier: core +--- + +Sensu's core/v2 API provides GET, POST, PUT, and DELETE access to Sensu events and resources. +The core/v2 API includes endpoints for the following Sensu resources: + +{{< coreapiListing >}} diff --git a/content/sensu-go/6.12/api/core/apikeys.md b/content/sensu-go/6.12/api/core/apikeys.md new file mode 100644 index 0000000000..3ead75f7e6 --- /dev/null +++ b/content/sensu-go/6.12/api/core/apikeys.md @@ -0,0 +1,232 @@ +--- +title: "core/v2/apikeys" +description: "Read this API documentation for information about Sensu core/v2/apikeys API endpoints, with examples for retrieving and managing Sensu API keys." +core_api_title: "core/v2/apikeys" +type: "core_api" +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: core +--- + +{{% notice note %}} +**NOTE**: Requests to `core/v2/apikeys` endpoints require you to authenticate with a Sensu [API key](../../#configure-an-environment-variable-for-api-key-authentication) or [access token](../../#authenticate-with-auth-api-endpoints). +The code examples in this document use the [environment variable](../../#configure-an-environment-variable-for-api-key-authentication) `$SENSU_API_KEY` to represent a valid API key in API requests. +{{% /notice %}} + +## Get all API keys + +The `/apikeys` GET endpoint retrieves all API keys. + +### Example {#apikeys-get-example} + +The following example demonstrates a GET request to the `/apikeys` API endpoint: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/core/v2/apikeys \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request will result in a successful `HTTP/1.1 200 OK` response and a JSON array that contains all API keys, similar to this example: + +{{< code text >}} +[ + { + "metadata": { + "name": "83abef1e-e7d7-4beb-91fc-79ad90084d5b", + "created_by": "admin" + }, + "username": "admin", + "created_at": 1570640363 + }, + { + "metadata": { + "name": "94jhid83j-96kg-2ewr-bab3-ppd3d49tdd94", + "created_by": "admin" + }, + "username": "admin", + "created_at": 1651257929 + } +] +{{< /code >}} + +### API Specification {#apikeys-get-specification} + +/apikeys (GET) | +---------------|------ +description | Returns the list of API keys. +example url | http://hostname:8080/api/core/v2/apikeys +pagination | This endpoint supports pagination using the `limit` and `continue` query parameters. Read the [API overview][1] for details. +response type | Array +response codes |
  • **Success**: 200 (OK)
  • **Error**: 500 (Internal Server Error)
+output | {{< code text >}} +[ + { + "metadata": { + "name": "83abef1e-e7d7-4beb-91fc-79ad90084d5b", + "created_by": "admin" + }, + "username": "admin", + "created_at": 1570640363 + }, + { + "metadata": { + "name": "94jhid83j-96kg-2ewr-bab3-ppd3d49tdd94", + "created_by": "admin" + }, + "username": "admin", + "created_at": 1651257929 + } +] +{{< /code >}} + +## Create a new API key + +The `/apikeys` API endpoint provides HTTP POST access to create a new API key. + +### Example {#apikeys-post-example} + +In the following example, an HTTP POST request is submitted to the `/apikeys` API endpoint to create a new API key. + +{{% notice note %}} +**NOTE**: For the `/apikeys` POST endpoint, authenticate with a Sensu access token, which you can generate with [/auth API endpoints](../../#authenticate-with-auth-api-endpoints) or [sensuctl](../../#generate-an-api-access-token-with-sensuctl). +This example uses `$SENSU_ACCESS_TOKEN` to represent a valid Sensu access token.

+If you prefer, you can [create a new API key with sensuctl](../../../operations/control-access/use-apikeys/#sensuctl-management-commands) instead of using this endpoint. +{{% /notice %}} + +{{< code shell >}} +curl -X POST \ +-H "Authorization: Bearer $SENSU_ACCESS_TOKEN" \ +-H 'Content-Type: application/json' \ +-d '{ + "username": "admin" +}' \ +http://127.0.0.1:8080/api/core/v2/apikeys +{{< /code >}} + +The request returns a successful HTTP `HTTP/1.1 201 Created` response, along with a `Location` header that contains the relative path to the new API key. + +### API Specification {#apikeys-post-specification} + +/apikeys (POST) | +----------------|------ +description | Creates a new API key, a Sensu-generated universally unique identifier (UUID). The response will include HTTP 201 and a `Location` header that contains the relative path to the new API key. +example URL | http://hostname:8080/api/core/v2/apikeys +request payload | {{< code shell >}} +{ + "username": "admin" +} +{{< /code >}} +response codes |
  • **Success**: 201 (Created)
  • **Malformed**: 400 (Bad Request)
  • **Error**: 500 (Internal Server Error)
+ +## Get a specific API key + +The `/apikeys/:apikey` GET endpoint retrieves the specified API key. + +### Example {#apikeysapikey-get-example} + +The following example queries the `/apikeys/:apikey` API: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/core/v2/apikeys/83abef1e-e7d7-4beb-91fc-79ad90084d5b \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request returns a successful `HTTP/1.1 200 OK` response and the requested `:apikey` definition, similar to the example below, or an error if the key is not found: + +{{< code text >}} +{ + "metadata": { + "name": "83abef1e-e7d7-4beb-91fc-79ad90084d5b", + "created_by": "admin" + }, + "username": "admin", + "created_at": 1570640363 +} +{{< /code >}} + +### API Specification {#apikeysapikey-get-specification} + +/apikeys/:apikey (GET) | +---------------------|------ +description | Returns the specified API key. +example url | http://hostname:8080/api/core/v2/apikeys/83abef1e-e7d7-4beb-91fc-79ad90084d5b +response type | Map +response codes |
  • **Success**: 200 (OK)
  • **Missing**: 404 (Not Found)
  • **Error**: 500 (Internal Server Error)
+output | {{< code text >}} +{ + "metadata": { + "name": "83abef1e-e7d7-4beb-91fc-79ad90084d5b", + "created_by": "admin" + }, + "username": "admin", + "created_at": 1570640363 +} +{{< /code >}} + +## Update an API key with PATCH + +The `/apikeys/:apikey` PATCH endpoint updates the specified API key. + +{{% notice note %}} +**NOTE**: You cannot change a resource's `name` or `namespace` with a PATCH request. +{{% /notice %}} + +### Example + +The following example queries the `/apikeys/:apikey` API updates the username for the specified `:apikey` definition and returns a successful `HTTP/1.1 200 OK` response. + +We support [JSON merge patches][2], so you must set the `Content-Type` header to `application/merge-patch+json` for PATCH requests. + +{{< code shell >}} +curl -X PATCH \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/merge-patch+json' \ +{ + "username": "devteam" +} \ +http://127.0.0.1:8080/api/core/v2/apikeys/83abef1e-e7d7-4beb-91fc-79ad90084d5b +{{< /code >}} + +### API Specification + +/apikeys/:apikey (PATCH) | +---------------------|------ +description | Updates the specified API key. +example url | http://hostname:8080/api/core/v2/apikeys/83abef1e-e7d7-4beb-91fc-79ad90084d5b +response type | Map +response codes |
  • **Success**: 200 (OK)
  • **Missing**: 404 (Not Found)
  • **Error**: 500 (Internal Server Error)
+output | {{< code json >}} +{ + "username": "devteam" +} +{{< /code >}} + +## Delete an API key {#apikeysapikey-delete} + +The `/apikeys/:apikey` API endpoint provides HTTP DELETE access to remove an API key. + +### Example {#apikeysapikey-delete-example} + +The following example shows a request to the `/apikeys/:apikey` API endpoint to delete the API key `83abef1e-e7d7-4beb-91fc-79ad90084d5b`, resulting in a successful `HTTP/1.1 204 No Content` response. + +{{< code shell >}} +curl -X DELETE \ +-H "Authorization: Key $SENSU_API_KEY" \ +http://127.0.0.1:8080/api/core/v2/apikeys/83abef1e-e7d7-4beb-91fc-79ad90084d5b +{{< /code >}} + +### API Specification {#apikeysapikey-delete-specification} + +/apikeys/:apikey (DELETE) | +----------------|------ +description | Revokes the specified API key. +example URL | http://hostname:8080/api/core/v2/apikeys/83abef1e-e7d7-4beb-91fc-79ad90084d5b +response codes |
  • **Success**: 204 (No Content)
  • **Error**: 500 (Internal Server Error)
+ + +[1]: ../../#pagination +[2]: https://tools.ietf.org/html/rfc7396 diff --git a/content/sensu-go/6.12/api/core/assets.md b/content/sensu-go/6.12/api/core/assets.md new file mode 100644 index 0000000000..d7ecb7ba6f --- /dev/null +++ b/content/sensu-go/6.12/api/core/assets.md @@ -0,0 +1,583 @@ +--- +title: "core/v2/assets" +description: "Read this API documentation for information about Sensu core/v2/assets API endpoints, with examples for retrieving and managing dynamic runtime assets." +core_api_title: "core/v2/assets" +type: "core_api" +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: core +--- + +{{% notice note %}} +**NOTE**: Requests to `core/v2/assets` API endpoints require you to authenticate with a Sensu [API key](../../#configure-an-environment-variable-for-api-key-authentication) or [access token](../../#authenticate-with-auth-api-endpoints). +The code examples in this document use the [environment variable](../../#configure-an-environment-variable-for-api-key-authentication) `$SENSU_API_KEY` to represent a valid API key in API requests. +{{% /notice %}} + +## Get all assets + +The `/assets` API endpoint provides HTTP GET access to [dynamic runtime asset][1] data. + +### Example {#assets-get-example} + +The following example demonstrates a GET request to the `/assets` API endpoint: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/assets \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request results in a successful `HTTP/1.1 200 OK` response and a JSON array that contains [dynamic runtime asset definitions][1], similar to this example: + +{{< code text >}} +[ + { + "url": "https://github.com/sensu/sensu-influxdb-handler/releases/download/3.1.2/sensu-influxdb-handler_3.1.2_linux_amd64.tar.gz", + "sha512": "612c6ff9928841090c4d23bf20aaf7558e4eed8977a848cf9e2899bb13a13e7540bac2b63e324f39d9b1257bb479676bc155b24e21bf93c722b812b0f15cb3bd", + "filters": [ + "entity.system.os == 'linux'", + "entity.system.arch == 'amd64'" + ], + "builds": null, + "metadata": { + "name": "sensu-influxdb-handler", + "namespace": "default", + "created_by": "admin" + }, + "headers": { + "Authorization": "Bearer $TOKEN", + "X-Forwarded-For": "client1, proxy1, proxy2" + } + }, + { + "url": "https://github.com/sensu/sensu-slack-handler/releases/download/1.0.3/sensu-slack-handler_1.0.3_linux_amd64.tar.gz", + "sha512": "68720865127fbc7c2fe16ca4d7bbf2a187a2df703f4b4acae1c93e8a66556e9079e1270521999b5871473e6c851f51b34097c54fdb8d18eedb7064df9019adc8", + "filters": [ + "entity.system.os == 'linux'", + "entity.system.arch == 'amd64'" + ], + "builds": null, + "metadata": { + "name": "sensu-slack-handler", + "namespace": "default", + "created_by": "admin" + }, + "headers": { + "Authorization": "Bearer $TOKEN", + "X-Forwarded-For": "client1, proxy1, proxy2" + } + } +] +{{< /code >}} + +### API Specification {#assets-get-specification} + +/assets (GET) | +---------------|------ +description | Returns the list of dynamic runtime assets. +example url | http://hostname:8080/api/core/v2/namespaces/default/assets +pagination | This endpoint supports [pagination][2] using the `limit` and `continue` query parameters. +response filtering | This endpoint supports [API response filtering][3]. +response type | Array +response codes |
  • **Success**: 200 (OK)
  • **Error**: 500 (Internal Server Error)
+output | {{< code text >}} +[ + { + "url": "https://github.com/sensu/sensu-influxdb-handler/releases/download/3.1.2/sensu-influxdb-handler_3.1.2_linux_amd64.tar.gz", + "sha512": "612c6ff9928841090c4d23bf20aaf7558e4eed8977a848cf9e2899bb13a13e7540bac2b63e324f39d9b1257bb479676bc155b24e21bf93c722b812b0f15cb3bd", + "filters": [ + "entity.system.os == 'linux'", + "entity.system.arch == 'amd64'" + ], + "builds": null, + "metadata": { + "name": "sensu-influxdb-handler", + "namespace": "default", + "created_by": "admin" + }, + "headers": { + "Authorization": "Bearer $TOKEN", + "X-Forwarded-For": "client1, proxy1, proxy2" + } + }, + { + "url": "https://github.com/sensu/sensu-slack-handler/releases/download/1.0.3/sensu-slack-handler_1.0.3_linux_amd64.tar.gz", + "sha512": "68720865127fbc7c2fe16ca4d7bbf2a187a2df703f4b4acae1c93e8a66556e9079e1270521999b5871473e6c851f51b34097c54fdb8d18eedb7064df9019adc8", + "filters": [ + "entity.system.os == 'linux'", + "entity.system.arch == 'amd64'" + ], + "builds": null, + "metadata": { + "name": "sensu-slack-handler", + "namespace": "default", + "created_by": "admin" + }, + "headers": { + "Authorization": "Bearer $TOKEN", + "X-Forwarded-For": "client1, proxy1, proxy2" + } + } +] +{{< /code >}} + +## Create a new dynamic runtime asset + +The `/assets` API endpoint provides HTTP POST access to [dynamic runtime asset][1] data. + +### Example {#assets-post-example} + +In the following example, an HTTP POST request is submitted to the `/assets` API endpoint to create a role named `sensu-slack-handler`: + +{{< code shell >}} +curl -X POST \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "url": "https://github.com/sensu/sensu-slack-handler/releases/download/1.0.3/sensu-slack-handler_1.0.3_linux_amd64.tar.gz", + "sha512": "68720865127fbc7c2fe16ca4d7bbf2a187a2df703f4b4acae1c93e8a66556e9079e1270521999b5871473e6c851f51b34097c54fdb8d18eedb7064df9019adc8", + "filters": [ + "entity.system.os == 'linux'", + "entity.system.arch == 'amd64'" + ], + "headers": { + "Authorization": "Bearer $TOKEN", + "X-Forwarded-For": "client1, proxy1, proxy2" + }, + "metadata": { + "name": "sensu-slack-handler", + "namespace": "default" + } +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/assets +{{< /code >}} + +The request returns a successful `HTTP/1.1 201 Created` response. + +### API Specification {#assets-post-specification} + +/assets (POST) | +----------------|------ +description | Creates a Sensu dynamic runtime asset. +example URL | http://hostname:8080/api/core/v2/namespaces/default/assets +payload | {{< code shell >}} +{ + "url": "https://github.com/sensu/sensu-slack-handler/releases/download/1.0.3/sensu-slack-handler_1.0.3_linux_amd64.tar.gz", + "sha512": "68720865127fbc7c2fe16ca4d7bbf2a187a2df703f4b4acae1c93e8a66556e9079e1270521999b5871473e6c851f51b34097c54fdb8d18eedb7064df9019adc8", + "filters": [ + "entity.system.os == 'linux'", + "entity.system.arch == 'amd64'" + ], + "headers": { + "Authorization": "Bearer $TOKEN", + "X-Forwarded-For": "client1, proxy1, proxy2" + }, + "metadata": { + "name": "sensu-slack-handler", + "namespace": "default" + } +} +{{< /code >}} +response codes |
  • **Success**: 201 (Created)
  • **Malformed**: 400 (Bad Request)
  • **Error**: 500 (Internal Server Error)
+ +## Get a specific dynamic runtime asset {#assetsasset-get} + +The `/assets/:asset` API endpoint provides HTTP GET access to [dynamic runtime asset data][1] for specific `:asset` definitions, by asset `name`. + +### Example {#assetsasset-get-example} + +The following example queries the `/assets/:asset` API endpoint for the `:asset` named `check_script`: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/assets/sensu-slack-handler \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request will return a successful `HTTP/1.1 200 OK` response and a JSON map that contains the requested [`:asset` definition][1] (in this example, for the `:asset` named `check_script`): + +{{< code text >}} +[ + { + "url": "https://github.com/sensu/sensu-slack-handler/releases/download/1.0.3/sensu-slack-handler_1.0.3_linux_amd64.tar.gz", + "sha512": "68720865127fbc7c2fe16ca4d7bbf2a187a2df703f4b4acae1c93e8a66556e9079e1270521999b5871473e6c851f51b34097c54fdb8d18eedb7064df9019adc8", + "filters": [ + "entity.system.os == 'linux'", + "entity.system.arch == 'amd64'" + ], + "builds": null, + "metadata": { + "name": "sensu-slack-handler", + "namespace": "default", + "created_by": "admin" + }, + "headers": { + "Authorization": "Bearer $TOKEN", + "X-Forwarded-For": "client1, proxy1, proxy2" + } + } +] +{{< /code >}} + +### API Specification {#assetsasset-get-specification} + +/assets/:asset (GET) | +---------------------|------ +description | Returns the specified dynamic runtime asset. +example url | http://hostname:8080/api/core/v2/namespaces/default/assets/sensu-slack-handler +response type | Map +response codes |
  • **Success**: 200 (OK)
  • **Missing**: 404 (Not Found)
  • **Error**: 500 (Internal Server Error)
+output | {{< code text >}} +[ + { + "url": "https://github.com/sensu/sensu-slack-handler/releases/download/1.0.3/sensu-slack-handler_1.0.3_linux_amd64.tar.gz", + "sha512": "68720865127fbc7c2fe16ca4d7bbf2a187a2df703f4b4acae1c93e8a66556e9079e1270521999b5871473e6c851f51b34097c54fdb8d18eedb7064df9019adc8", + "filters": [ + "entity.system.os = 'linux'", + "entity.system.arch = 'amd64'" + ], + "builds": null, + "metadata": { + "name": "sensu-slack-handler", + "namespace": "default", + "created_by": "admin" + }, + "headers": { + "Authorization": "Bearer $TOKEN", + "X-Forwarded-For": "client1, proxy1, proxy2" + } + } +] +{{< /code >}} + +## Create or update a dynamic runtime asset {#assetsasset-put} + +The `/assets/:asset` API endpoint provides HTTP PUT access to create or update specific `:asset` definitions, by dynamic runtime asset name. + +### Example {#assetsasset-put-example} + +In the following example, an HTTP PUT request is submitted to the `/assets/:asset` API endpoint to create the dynamic runtime asset `sensu-slack-handler`: + +{{< code shell >}} +curl -X PUT \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "url": "https://github.com/sensu/sensu-slack-handler/releases/download/1.0.3/sensu-slack-handler_1.0.3_linux_amd64.tar.gz", + "sha512": "68720865127fbc7c2fe16ca4d7bbf2a187a2df703f4b4acae1c93e8a66556e9079e1270521999b5871473e6c851f51b34097c54fdb8d18eedb7064df9019adc8", + "filters": [ + "entity.system.os == 'linux'", + "entity.system.arch == 'amd64'" + ], + "headers": { + "Authorization": "Bearer $TOKEN", + "X-Forwarded-For": "client1, proxy1, proxy2" + }, + "metadata": { + "name": "sensu-slack-handler", + "namespace": "default" + } +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/rolebindings/sensu-slack-handler +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#assetsasset-put-specification} + +/assets/:asset (PUT) | +----------------|------ +description | Creates or updates the specified Sensu dynamic runtime asset. +example URL | http://hostname:8080/api/core/v2/namespaces/default/assets/sensu-slack-handler +payload | {{< code shell >}} +{ + "url": "https://github.com/sensu/sensu-slack-handler/releases/download/1.0.3/sensu-slack-handler_1.0.3_linux_amd64.tar.gz", + "sha512": "68720865127fbc7c2fe16ca4d7bbf2a187a2df703f4b4acae1c93e8a66556e9079e1270521999b5871473e6c851f51b34097c54fdb8d18eedb7064df9019adc8", + "filters": [ + "entity.system.os == 'linux'", + "entity.system.arch == 'amd64'" + ], + "headers": { + "Authorization": "Bearer $TOKEN", + "X-Forwarded-For": "client1, proxy1, proxy2" + }, + "metadata": { + "name": "sensu-slack-handler", + "namespace": "default" + } +} +{{< /code >}} +response codes |
  • **Success**: 201 (Created)
  • **Malformed**: 400 (Bad Request)
  • **Error**: 500 (Internal Server Error)
+ +## Update a dynamic runtime asset with PATCH + +The `/assets/:asset` API endpoint provides HTTP PATCH access to update `:asset` definitions, specified by asset name. + +{{% notice note %}} +**NOTE**: You cannot change a resource's `name` or `namespace` with a PATCH request. +Use a [PUT request](#assetsasset-put) instead.

+Also, you cannot add elements to an array with a PATCH request — you must replace the entire array. +{{% /notice %}} + +### Example + +In the following example, an HTTP PATCH request is submitted to the `/assets/:asset` API endpoint to add a label for the `sensu-slack-handler` asset. + +We support [JSON merge patches][4], so you must set the `Content-Type` header to `application/merge-patch+json` for PATCH requests. + +{{< code shell >}} +curl -X PATCH \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/merge-patch+json' \ +-d '{ + "metadata": { + "labels": { + "region": "us-west-1" + } + } +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/assets/sensu-slack-handler +{{< /code >}} + +The request will return a successful `HTTP/1.1 200 OK` response. + +### API Specification + +/assets/:asset (PATCH) | +----------------|------ +description | Updates the specified Sensu asset. +example URL | http://hostname:8080/api/core/v2/namespaces/default/assets/sensu-slack-handler +payload | {{< code shell >}} +{ + "metadata": { + "labels": { + "region": "us-west-1" + } + } +} +{{< /code >}} +response codes |
  • **Success**: 200 (OK)
  • **Malformed**: 400 (Bad Request)
  • **Error**: 500 (Internal Server Error)
+ +## Delete a dynamic runtime asset {#assetsasset-delete} + +The `/assets/:asset` API endpoint provides HTTP DELETE access so you can delete a dynamic runtime assets. + +{{% notice note %}} +**NOTE**: Deleting a dynamic runtime asset does not remove the downloaded files from the asset cache or remove any references to the deleted asset in other resources. +{{% /notice %}} + +### Example {#assetsasset-delete-example} + +The following example shows a request to the `/assets/:asset` API endpoint to delete the asset `sensu-slack-handler`, resulting in a successful `HTTP/1.1 204 No Content` response: + +{{< code shell >}} +curl -X DELETE \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/assets/sensu-slack-handler \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +### API Specification {#assetsasset-delete-specification} + +/assets/:asset (DELETE) | +----------------|------ +description | Deletes the specified Sensu dynamic runtime asset. +example URL | http://hostname:8080/api/core/v2/namespaces/default/assets/sensu-slack-handler +response codes |
  • **Success**: 204 (No Content)
  • **Missing**: 404 (Not Found)
  • **Error**: 500 (Internal Server Error)
+ +## Get a subset of assets with response filtering + +The `/assets` API endpoint supports [response filtering][3] for a subset of asset data based on labels and the following fields: + +- `asset.name` +- `asset.namespace` +- `asset.filters` + +### Example + +The following example demonstrates a request to the `/assets` API endpoint with response filtering that excludes [dynamic runtime asset definitions][1] that are in the `production` namespace: + +{{< code shell >}} +curl -H "Authorization: Key X" http://127.0.0.1:8080/api/core/v2/assets -G \ +--data-urlencode 'fieldSelector=asset.namespace != "production"' +{{< /code >}} + +{{% notice note %}} +**NOTE**: Read [API response filtering](../../#response-filtering) for more filter statement examples that demonstrate how to filter responses using different operators with label and field selectors. +{{% /notice %}} + +The example request will result in a successful `HTTP/1.1 200 OK` response and a JSON array that contains only [dynamic runtime asset definitions][1] that are **not** in the `production` namespace: + +{{< code text >}} +[ + { + "filters": null, + "builds": [ + { + "url": "https://assets.bonsai.sensu.io/a7ced27e881989c44522112aa05dd3f25c8f1e49/check-cpu-usage_0.2.2_windows_amd64.tar.gz", + "sha512": "900cfdf28d6088b929c4bf9a121b628971edee5fa5cbc91a6bc1df3bd9a7f8adb1fcfb7b1ad70589ed5b4f5ec87d9a9a3ba95bcf2acda56b0901406f14f69fe7", + "filters": [ + "entity.system.os == 'windows'", + "entity.system.arch == 'amd64'" + ], + "headers": null + }, + { + "url": "https://assets.bonsai.sensu.io/a7ced27e881989c44522112aa05dd3f25c8f1e49/check-cpu-usage_0.2.2_darwin_amd64.tar.gz", + "sha512": "db81ee70426114e4cd4b3f180f2b0b1e15b4bffc09d7f2b41a571be2422f4399af3fbd2fa2918b8831909ab4bc2d3f58d0aa0d7b197d3a218b2391bb5c1f6913", + "filters": [ + "entity.system.os == 'darwin'", + "entity.system.arch == 'amd64'" + ], + "headers": null + }, + { + "url": "https://assets.bonsai.sensu.io/a7ced27e881989c44522112aa05dd3f25c8f1e49/check-cpu-usage_0.2.2_linux_armv7.tar.gz", + "sha512": "400aacce297176e69f3a88b0aab0ddfdbe9dd6a37a673cb1774c8d4750a91cf7713a881eef26ea21d200f74cb20818161c773490139e6a6acb92cbd06dee994c", + "filters": [ + "entity.system.os == 'linux'", + "entity.system.arch == 'armv7'" + ], + "headers": null + }, + { + "url": "https://assets.bonsai.sensu.io/a7ced27e881989c44522112aa05dd3f25c8f1e49/check-cpu-usage_0.2.2_linux_arm64.tar.gz", + "sha512": "bef7802b121ac2a2a5c5ad169d6003f57d8b4f5e83eae998a0e0dd1e7b89678d4a62e678d153edacdd65fd1d0123b5f51308622690455e77cec6deccfa183397", + "filters": [ + "entity.system.os == 'linux'", + "entity.system.arch == 'arm64'" + ], + "headers": null + }, + { + "url": "https://assets.bonsai.sensu.io/a7ced27e881989c44522112aa05dd3f25c8f1e49/check-cpu-usage_0.2.2_linux_386.tar.gz", + "sha512": "a2dcb5324952567a61d76a2e331c1c16df69ef0e0b9899515dad8d1531b204076ad0c008f59fc2f4735a5a779afb0c1baa132268c41942b203444e377fe8c8e5", + "filters": [ + "entity.system.os == 'linux'", + "entity.system.arch == '386'" + ], + "headers": null + }, + { + "url": "https://assets.bonsai.sensu.io/a7ced27e881989c44522112aa05dd3f25c8f1e49/check-cpu-usage_0.2.2_linux_amd64.tar.gz", + "sha512": "24539739b5eb19bbab6eda151d0bcc63a0825afdfef3bc1ec3670c7b0a00fbbb2fd006d605a7a038b32269a22026d8947324f2bc0acdf35e8563cf4cb8660d7f", + "filters": [ + "entity.system.os == 'linux'", + "entity.system.arch == 'amd64'" + ], + "headers": null + } + ], + "metadata": { + "name": "check-cpu-usage", + "namespace": "default", + "annotations": { + "io.sensu.bonsai.api_url": "https://bonsai.sensu.io/api/v1/assets/sensu/check-cpu-usage", + "io.sensu.bonsai.name": "check-cpu-usage", + "io.sensu.bonsai.namespace": "sensu", + "io.sensu.bonsai.tags": "", + "io.sensu.bonsai.tier": "Community", + "io.sensu.bonsai.url": "https://bonsai.sensu.io/assets/sensu/check-cpu-usage", + "io.sensu.bonsai.version": "0.2.2" + }, + "created_by": "admin" + }, + "headers": null + } +] +{{< /code >}} + +### API Specification + +/assets (GET) with response filters | +---------------|------ +description | Returns the list of assets that match the [response filters][3] applied in the API request. +example url | http://hostname:8080/api/core/v2/assets +pagination | This endpoint supports [pagination][2] using the `limit` and `continue` query parameters. +response type | Array +response codes |
  • **Success**: 200 (OK)
  • **Error**: 500 (Internal Server Error)
+output | {{< code text >}} +[ + { + "filters": null, + "builds": [ + { + "url": "https://assets.bonsai.sensu.io/a7ced27e881989c44522112aa05dd3f25c8f1e49/check-cpu-usage_0.2.2_windows_amd64.tar.gz", + "sha512": "900cfdf28d6088b929c4bf9a121b628971edee5fa5cbc91a6bc1df3bd9a7f8adb1fcfb7b1ad70589ed5b4f5ec87d9a9a3ba95bcf2acda56b0901406f14f69fe7", + "filters": [ + "entity.system.os == 'windows'", + "entity.system.arch == 'amd64'" + ], + "headers": null + }, + { + "url": "https://assets.bonsai.sensu.io/a7ced27e881989c44522112aa05dd3f25c8f1e49/check-cpu-usage_0.2.2_darwin_amd64.tar.gz", + "sha512": "db81ee70426114e4cd4b3f180f2b0b1e15b4bffc09d7f2b41a571be2422f4399af3fbd2fa2918b8831909ab4bc2d3f58d0aa0d7b197d3a218b2391bb5c1f6913", + "filters": [ + "entity.system.os == 'darwin'", + "entity.system.arch == 'amd64'" + ], + "headers": null + }, + { + "url": "https://assets.bonsai.sensu.io/a7ced27e881989c44522112aa05dd3f25c8f1e49/check-cpu-usage_0.2.2_linux_armv7.tar.gz", + "sha512": "400aacce297176e69f3a88b0aab0ddfdbe9dd6a37a673cb1774c8d4750a91cf7713a881eef26ea21d200f74cb20818161c773490139e6a6acb92cbd06dee994c", + "filters": [ + "entity.system.os == 'linux'", + "entity.system.arch == 'armv7'" + ], + "headers": null + }, + { + "url": "https://assets.bonsai.sensu.io/a7ced27e881989c44522112aa05dd3f25c8f1e49/check-cpu-usage_0.2.2_linux_arm64.tar.gz", + "sha512": "bef7802b121ac2a2a5c5ad169d6003f57d8b4f5e83eae998a0e0dd1e7b89678d4a62e678d153edacdd65fd1d0123b5f51308622690455e77cec6deccfa183397", + "filters": [ + "entity.system.os == 'linux'", + "entity.system.arch == 'arm64'" + ], + "headers": null + }, + { + "url": "https://assets.bonsai.sensu.io/a7ced27e881989c44522112aa05dd3f25c8f1e49/check-cpu-usage_0.2.2_linux_386.tar.gz", + "sha512": "a2dcb5324952567a61d76a2e331c1c16df69ef0e0b9899515dad8d1531b204076ad0c008f59fc2f4735a5a779afb0c1baa132268c41942b203444e377fe8c8e5", + "filters": [ + "entity.system.os == 'linux'", + "entity.system.arch == '386'" + ], + "headers": null + }, + { + "url": "https://assets.bonsai.sensu.io/a7ced27e881989c44522112aa05dd3f25c8f1e49/check-cpu-usage_0.2.2_linux_amd64.tar.gz", + "sha512": "24539739b5eb19bbab6eda151d0bcc63a0825afdfef3bc1ec3670c7b0a00fbbb2fd006d605a7a038b32269a22026d8947324f2bc0acdf35e8563cf4cb8660d7f", + "filters": [ + "entity.system.os == 'linux'", + "entity.system.arch == 'amd64'" + ], + "headers": null + } + ], + "metadata": { + "name": "check-cpu-usage", + "namespace": "default", + "annotations": { + "io.sensu.bonsai.api_url": "https://bonsai.sensu.io/api/v1/assets/sensu/check-cpu-usage", + "io.sensu.bonsai.name": "check-cpu-usage", + "io.sensu.bonsai.namespace": "sensu", + "io.sensu.bonsai.tags": "", + "io.sensu.bonsai.tier": "Community", + "io.sensu.bonsai.url": "https://bonsai.sensu.io/assets/sensu/check-cpu-usage", + "io.sensu.bonsai.version": "0.2.2" + }, + "created_by": "admin" + }, + "headers": null + } +] +{{< /code >}} + + +[1]: ../../../plugins/assets/ +[2]: ../../#pagination +[3]: ../../#response-filtering +[4]: https://tools.ietf.org/html/rfc7396 diff --git a/content/sensu-go/6.12/api/core/checks.md b/content/sensu-go/6.12/api/core/checks.md new file mode 100644 index 0000000000..2257558780 --- /dev/null +++ b/content/sensu-go/6.12/api/core/checks.md @@ -0,0 +1,837 @@ +--- +title: "core/v2/checks" +description: "Read this API documentation for information about Sensu core/v2/checks API endpoints, with examples for retrieving and managing check definitions." +core_api_title: "core/v2/checks" +type: "core_api" +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: core +--- + +{{% notice note %}} +**NOTE**: Requests to `core/v2/checks` API endpoints require you to authenticate with a Sensu [API key](../../#configure-an-environment-variable-for-api-key-authentication) or [access token](../../#authenticate-with-auth-api-endpoints). +The code examples in this document use the [environment variable](../../#configure-an-environment-variable-for-api-key-authentication) `$SENSU_API_KEY` to represent a valid API key in API requests. +{{% /notice %}} + +## Get all checks + +The `/checks` API endpoint provides HTTP GET access to [check][1] data. + +### Example {#checks-get-example} + +The following example demonstrates a GET request to the `/checks` API endpoint: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/checks \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request results in a successful `HTTP/1.1 200 OK` response and a JSON array that contains the [check definitions][1] in the `default` namespace: + +{{< code text >}} +[ + { + "command": "check-cpu-usage -w 75 -c 90", + "handlers": [], + "high_flap_threshold": 0, + "interval": 60, + "low_flap_threshold": 0, + "publish": true, + "runtime_assets": [ + "check-cpu-usage" + ], + "subscriptions": [ + "system" + ], + "proxy_entity_name": "", + "check_hooks": null, + "stdin": false, + "subdue": null, + "ttl": 0, + "timeout": 0, + "round_robin": false, + "output_metric_format": "", + "output_metric_handlers": null, + "env_vars": null, + "metadata": { + "name": "check_cpu", + "namespace": "default", + "created_by": "admin" + }, + "secrets": null, + "pipelines": [ + { + "api_version": "core/v2", + "type": "Pipeline", + "name": "incident_alerts" + } + ] + }, + { + "command": "http-perf --url http://localhost --warning 1s --critical 2s", + "handlers": [], + "high_flap_threshold": 0, + "interval": 15, + "low_flap_threshold": 0, + "publish": true, + "runtime_assets": [ + "http-checks" + ], + "subscriptions": [ + "webserver" + ], + "proxy_entity_name": "", + "check_hooks": null, + "stdin": false, + "subdue": null, + "ttl": 0, + "timeout": 0, + "round_robin": false, + "output_metric_format": "nagios_perfdata", + "output_metric_handlers": "sensu_to_sumo", + "env_vars": null, + "metadata": { + "name": "collect-metrics", + "namespace": "default", + "created_by": "admin" + }, + "secrets": null, + "pipelines": [] + }, + { + "command": "sensu-prometheus-collector -prom-url http://localhost:9090 -prom-query up", + "handlers": [], + "high_flap_threshold": 0, + "interval": 10, + "low_flap_threshold": 0, + "publish": true, + "runtime_assets": [ + "sensu-prometheus-collector" + ], + "subscriptions": [ + "app_tier" + ], + "proxy_entity_name": "", + "check_hooks": null, + "stdin": false, + "subdue": null, + "ttl": 0, + "timeout": 0, + "round_robin": false, + "output_metric_format": "influxdb_line", + "output_metric_handlers": null, + "env_vars": null, + "metadata": { + "name": "prometheus_metrics", + "namespace": "default", + "labels": { + "sensu.io/managed_by": "sensuctl" + }, + "created_by": "admin" + }, + "secrets": null, + "pipelines": [ + { + "name": "prometheus_metrics_workflows", + "type": "Pipeline", + "api_version": "core/v2" + } + ] + } +] +{{< /code >}} + +### API Specification {#check-get-specification} + +/checks (GET) | +---------------|------ +description | Returns the list of checks. +example url | http://hostname:8080/api/core/v2/namespaces/default/checks +pagination | This endpoint supports [pagination][4] using the `limit` and `continue` query parameters. +response filtering | This endpoint supports [API response filtering][5]. +response type | Array +response codes |
  • **Success**: 200 (OK)
  • **Error**: 500 (Internal Server Error)
+output | {{< code text >}} +[ + { + "command": "check-cpu-usage -w 75 -c 90", + "handlers": [], + "high_flap_threshold": 0, + "interval": 60, + "low_flap_threshold": 0, + "publish": true, + "runtime_assets": [ + "check-cpu-usage" + ], + "subscriptions": [ + "system" + ], + "proxy_entity_name": "", + "check_hooks": null, + "stdin": false, + "subdue": null, + "ttl": 0, + "timeout": 0, + "round_robin": false, + "output_metric_format": "", + "output_metric_handlers": null, + "env_vars": null, + "metadata": { + "name": "check_cpu", + "namespace": "default", + "created_by": "admin" + }, + "secrets": null, + "pipelines": [ + { + "api_version": "core/v2", + "type": "Pipeline", + "name": "incident_alerts" + } + ] + }, + { + "command": "http-perf --url http://localhost --warning 1s --critical 2s", + "handlers": [], + "high_flap_threshold": 0, + "interval": 15, + "low_flap_threshold": 0, + "publish": true, + "runtime_assets": [ + "http-checks" + ], + "subscriptions": [ + "webserver" + ], + "proxy_entity_name": "", + "check_hooks": null, + "stdin": false, + "subdue": null, + "ttl": 0, + "timeout": 0, + "round_robin": false, + "output_metric_format": "nagios_perfdata", + "output_metric_handlers": "sensu_to_sumo", + "env_vars": null, + "metadata": { + "name": "collect-metrics", + "namespace": "default", + "created_by": "admin" + }, + "secrets": null, + "pipelines": [] + }, + { + "command": "sensu-prometheus-collector -prom-url http://localhost:9090 -prom-query up", + "handlers": [], + "high_flap_threshold": 0, + "interval": 10, + "low_flap_threshold": 0, + "publish": true, + "runtime_assets": [ + "sensu-prometheus-collector" + ], + "subscriptions": [ + "app_tier" + ], + "proxy_entity_name": "", + "check_hooks": null, + "stdin": false, + "subdue": null, + "ttl": 0, + "timeout": 0, + "round_robin": false, + "output_metric_format": "influxdb_line", + "output_metric_handlers": null, + "env_vars": null, + "metadata": { + "name": "prometheus_metrics", + "namespace": "default", + "labels": { + "sensu.io/managed_by": "sensuctl" + }, + "created_by": "admin" + }, + "secrets": null, + "pipelines": [ + { + "name": "prometheus_metrics_workflows", + "type": "Pipeline", + "api_version": "core/v2" + } + ] + } +] +{{< /code >}} + +## Create a new check + +The `/checks` API endpoint provides HTTP POST access to create checks. + +### Example {#checks-post-example} + +In the following example, an HTTP POST request is submitted to the `/checks` API endpoint to create a `check_cpu` check. +The request includes the check definition in the request body. + +{{< code shell >}} +curl -X POST \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "command": "check-cpu-usage.sh -w 75 -c 90", + "subscriptions": [ + "system" + ], + "interval": 60, + "publish": true, + "pipelines": [ + { + "api_version": "core/v2", + "type": "Pipeline", + "name": "incident_alerts" + } + ], + "runtime_assets": [ + "check-cpu-usage" + ], + "metadata": { + "name": "check_cpu", + "namespace": "default" + } +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/checks +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#checks-post-specification} + +/checks (POST) | +----------------|------ +description | Creates a Sensu check. +example URL | http://hostname:8080/api/core/v2/namespaces/default/checks +example payload | {{< code shell >}} +{ + "command": "check-cpu-usage.sh -w 75 -c 90", + "subscriptions": [ + "system" + ], + "interval": 60, + "publish": true, + "pipelines": [ + { + "api_version": "core/v2", + "type": "Pipeline", + "name": "incident_alerts" + } + ], + "runtime_assets": [ + "check-cpu-usage" + ], + "metadata": { + "name": "check_cpu", + "namespace": "default" + } +} +{{< /code >}} +payload parameters | Required check attributes: `interval` (integer) or `cron` (string) and a `metadata` scope that contains `name` (string) and `namespace` (string). For more information about creating checks, read the [checks reference][1]. +response codes |
  • **Success**: 201 (Created)
  • **Malformed**: 400 (Bad Request)
  • **Error**: 500 (Internal Server Error)
+ +## Get a specific check {#checkscheck-get} + +The `/checks/:check` API endpoint provides HTTP GET access to `:check` definitions, specified by check name. + +### Example {#checkscheck-get-example} + +The following example queries the `/checks/:check` API endpoint for the `:check` named `check_cpu`: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/checks/check_cpu \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request will return a successful `HTTP/1.1 200 OK` response and a JSON map that contains the requested [`:check` definition][1] (in this example, `check_cpu`): + +{{< code shell >}} +{ + "command": "check-cpu-usage.sh -w 75 -c 90", + "handlers": [], + "high_flap_threshold": 0, + "interval": 60, + "low_flap_threshold": 0, + "publish": true, + "runtime_assets": [ + "check-cpu-usage" + ], + "subscriptions": [ + "system" + ], + "proxy_entity_name": "", + "check_hooks": null, + "stdin": false, + "subdue": null, + "ttl": 0, + "timeout": 0, + "round_robin": false, + "output_metric_format": "", + "output_metric_handlers": null, + "env_vars": null, + "metadata": { + "name": "check_cpu", + "namespace": "default", + "created_by": "admin" + }, + "secrets": null, + "pipelines": [ + { + "name": "incident_alerts", + "type": "Pipeline", + "api_version": "core/v2" + } + ] +} +{{< /code >}} + +### API Specification {#checkscheck-get-specification} + +/checks/:check (GET) | +---------------------|------ +description | Returns the specified check. +example url | http://hostname:8080/api/core/v2/namespaces/default/checks/check_cpu +response type | Map +response codes |
  • **Success**: 200 (OK)
  • **Missing**: 404 (Not Found)
  • **Error**: 500 (Internal Server Error)
+output | {{< code text >}} +{ + "command": "check-cpu-usage.sh -w 75 -c 90", + "handlers": [], + "high_flap_threshold": 0, + "interval": 60, + "low_flap_threshold": 0, + "publish": true, + "runtime_assets": [ + "check-cpu-usage" + ], + "subscriptions": [ + "system" + ], + "proxy_entity_name": "", + "check_hooks": null, + "stdin": false, + "subdue": null, + "ttl": 0, + "timeout": 0, + "round_robin": false, + "output_metric_format": "", + "output_metric_handlers": null, + "env_vars": null, + "metadata": { + "name": "check_cpu", + "namespace": "default", + "created_by": "admin" + }, + "secrets": null, + "pipelines": [ + { + "name": "incident_alerts", + "type": "Pipeline", + "api_version": "core/v2" + } + ] +} +{{< /code >}} + +## Create or update a check {#checkscheck-put} + +The `/checks/:check` API endpoint provides HTTP PUT access to create and update `:check` definitions, specified by check name. + +### Example {#checkscheck-put-example} + +In the following example, an HTTP PUT request is submitted to the `/checks/:check` API endpoint to update the `check_cpu` check: + +{{< code shell >}} +curl -X PUT \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "command": "check-cpu-usage.sh -w 75 -c 90", + "pipelines": [ + { + "api_version": "core/v2", + "type": "Pipeline", + "name": "incident_alerts" + } + ], + "interval": 60, + "publish": true, + "subscriptions": [ + "system" + ], + "metadata": { + "name": "check_cpu", + "namespace": "default" + } +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/checks/check_cpu +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#checkscheck-put-specification} + +/checks/:check (PUT) | +----------------|------ +description | Creates or updates the specified Sensu check. +example URL | http://hostname:8080/api/core/v2/namespaces/default/checks/check_cpu +payload | {{< code shell >}} +{ + "command": "check-cpu-usage.sh -w 75 -c 90", + "pipelines": [ + { + "api_version": "core/v2", + "type": "Pipeline", + "name": "incident_alerts" + } + ], + "interval": 60, + "publish": true, + "subscriptions": [ + "system" + ], + "metadata": { + "name": "check_cpu", + "namespace": "default" + } +} +{{< /code >}} +payload parameters | Required check attributes: `interval` (integer) or `cron` (string) and a `metadata` scope that contains `name` (string) and `namespace` (string). For more information about creating checks, read the [checks reference][1]. +response codes |
  • **Success**: 201 (Created)
  • **Malformed**: 400 (Bad Request)
  • **Error**: 500 (Internal Server Error)
+ +## Update a check with PATCH + +The `/checks/:check` API endpoint provides HTTP PATCH access to update `:check` definitions, specified by check name. + +{{% notice note %}} +**NOTE**: You cannot change a resource's `name` or `namespace` with a PATCH request. +Use a [PUT request](#checkscheck-put) instead.

+Also, you cannot add elements to an array with a PATCH request — you must replace the entire array. +{{% /notice %}} + +### Example + +In the following example, an HTTP PATCH request is submitted to the `/checks/:check` API endpoint to update the subscriptions array for the `check_cpu` check, resulting in a `HTTP/1.1 200 OK` response and the updated check definition. + +We support [JSON merge patches][6], so you must set the `Content-Type` header to `application/merge-patch+json` for PATCH requests. + +{{< code shell >}} +curl -X PATCH \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/merge-patch+json' \ +-d '{ + "subscriptions": [ + "system", + "health" + ] +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/checks/check_cpu +{{< /code >}} + +### API Specification + +/checks/:check (PATCH) | +----------------|------ +description | Updates the specified Sensu check. +example URL | http://hostname:8080/api/core/v2/namespaces/default/checks/check_cpu +payload | {{< code shell >}} +{ + "subscriptions": [ + "system", + "health" + ] +} +{{< /code >}} +response codes |
  • **Success**: 200 (OK)
  • **Malformed**: 400 (Bad Request)
  • **Error**: 500 (Internal Server Error)
+ +## Delete a check {#checkscheck-delete} + +The `/checks/:check` API endpoint provides HTTP DELETE access to delete a check from Sensu, specified by the check name. + +### Example {#checkscheck-delete-example} + +The following example shows a request to the `/checks/:check` API endpoint to delete the check named `check_cpu`, which will result in a successful `HTTP/1.1 204 No Content` response: + +{{< code shell >}} +curl -X DELETE \ +-H "Authorization: Key $SENSU_API_KEY" \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/checks/check_cpu +{{< /code >}} + +### API Specification {#checkscheck-delete-specification} + +/checks/:check (DELETE) | +--------------------------|------ +description | Removes the specified check from Sensu. +example url | http://hostname:8080/api/core/v2/namespaces/default/checks/check_cpu +response codes |
  • **Success**: 204 (No Content)
  • **Missing**: 404 (Not Found)
  • **Error**: 500 (Internal Server Error)
+ +## Create an ad hoc check execution request {#checkscheckexecute-post} + +The `/checks/:check/execute` API endpoint provides HTTP POST access to create an ad hoc check execution request so you can execute a check on demand. + +### Example {#checkscheckexecute-post-example} + +In the following example, an HTTP POST request is submitted to the `/checks/:check/execute` API endpoint to execute the `check_cpu` check. +The request includes the check name in the request body. + +{{% notice protip %}} +**PRO TIP**: Include the `subscriptions` attribute with the request body to override the subscriptions configured in the check definition. +This gives you the flexibility to execute a check on any Sensu entity or group of entities on demand. +{{% /notice %}} + +{{< code shell >}} +curl -X POST \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "check": "check_cpu", + "subscriptions": [ + "entity:i-424242" + ] +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/checks/check_cpu/execute +{{< /code >}} + +The request will return a successful `HTTP/1.1 202 Accepted` response and an `issued` timestamp: + +{{< code text >}} +{"issued":1543861798} +{{< /code >}} + +{{% notice note %}} +**NOTE**: If you specify a [round robin check](../../../observability-pipeline/observe-schedule/checks/#round-robin-checks), Sensu will execute the check on *all* agents with a matching subscription. +After the ad hoc execution, the check will run as scheduled in round robin fashion.

+To execute a round robin check on a single agent, include the agent's entity name subscription in the request body. +For example, if the entity is named `webserver1`, use the subscription `entity:webserver1`. +{{% /notice %}} + +### API Specification {#checkscheckexecute-post-specification} + +/checks/:check/execute (POST) | +----------------|------ +description | Creates an ad hoc request to execute the specified check. +example URL | http://hostname:8080/api/core/v2/namespaces/default/checks/check_cpu/execute +payload | {{< code shell >}} +{ + "check": "check_cpu", + "subscriptions": [ + "entity:i-424242" + ] +} +{{< /code >}} +payload parameters |
  • Required: `check` (the name of the check to execute).
  • Optional: `subscriptions` (an array of subscriptions to publish the check request to). When provided with the request, the `subscriptions` attribute overrides any subscriptions configured in the check definition.
    • +response codes |
    • **Success**: 202 (Accepted)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Assign a hook to a check {#checkscheckhooks-put} + +The `/checks/:check/hooks/:type` API endpoint provides HTTP PUT access to assign a [hook][2] to a check. + +### Example {#checkscheckhooks-put-example} + +In the following example, an HTTP PUT request is submitted to the `/checks/:check/hooks/:type` API endpoint, assigning the `process_tree` hook to the `check_cpu` check in the event of a `critical` type check result: + +{{< code shell >}} +curl -X PUT \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "critical": [ + "process_tree" + ] +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/checks/check_cpu/hooks/critical +{{< /code >}} + +The request returns a successful `HTTP/1.1 201 Created` response. + +### API Specification {#checkscheckhooks-put-specification} + +checks/:check/hooks/:type (PUT) | +----------------|------ +description | Assigns a hook to a check (specified by the check name and [check response type][3]). +example URL | http://hostname:8080/api/core/v2/namespaces/default/checks/check_cpu/hooks/critical +example payload | {{< code shell >}} +{ + "critical": [ + "process_tree" + ] +} +{{< /code >}} +payload parameters | This endpoint requires a JSON map of [check response types][3] (for example, `critical` or `warning`). Each must contain an array of hook names. +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Remove a hook from a check {#checkscheckhookshook-delete} + +The `/checks/:check/hooks/:type/hook/:hook` API endpoint provides HTTP DELETE access to a remove a [hook][2] from a [check][1]. + +### Example {#checkscheckhookshook-delete-example} + +The following example shows a request to the `/checks/:check/hooks/:type/hook/:hook` API endpoint to remove the `process_tree` hook from the `check_cpu` check, resulting in a successful `HTTP/1.1 204 No Content` response: + +{{< code shell >}} +curl -X DELETE \ +-H "Authorization: Key $SENSU_API_KEY" \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/checks/check_cpu/hooks/critical/hook/process_tree +{{< /code >}} + +### API Specification {#checkscheckhookshook-delete-specification} + +/checks/:check/hooks/:type/hook/:hook (DELETE) | +--------------------------|------ +description | Removes a single hook from a check (specified by the check name, check response type, and hook name). Read the [checks reference][3] for available types. +example url | http://hostname:8080/api/core/v2/namespaces/default/checks/check_cpu/hooks/critical/hook/process_tree +response codes |
    • **Success**: 204 (No Content)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + +## Get a subset of checks with response filtering + +The `/checks` API endpoint supports [response filtering][5] for a subset of check data based on labels and the following fields: + +- `check.name` +- `check.namespace` +- `check.handlers` +- `check.publish` +- `check.round_robin` +- `check.runtime_assets` +- `check.subscriptions` + +### Example + +The following example demonstrates a request to the `/checks` API endpoint with [response filtering][5] for only [check definitions][1] whose subscriptions include `system`: + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/checks -G \ +--data-urlencode 'fieldSelector="system" in check.subscriptions' +{{< /code >}} + +The example request will result in a successful `HTTP/1.1 200 OK` response and a JSON array that contains only [check definitions][1] whose subscriptions include `system`: + +{{< code text >}} +[ + { + "command": "check-cpu-usage.sh -w 75 -c 90", + "handlers": [], + "high_flap_threshold": 0, + "interval": 60, + "low_flap_threshold": 0, + "publish": true, + "runtime_assets": [ + "check-cpu-usage" + ], + "subscriptions": [ + "system", + "health" + ], + "proxy_entity_name": "", + "check_hooks": [ + { + "critical": [ + "process_tree" + ] + } + ], + "stdin": false, + "subdue": null, + "ttl": 0, + "timeout": 0, + "round_robin": false, + "output_metric_format": "", + "output_metric_handlers": null, + "env_vars": null, + "metadata": { + "name": "check_cpu", + "namespace": "default", + "created_by": "admin" + }, + "secrets": null, + "pipelines": [ + { + "name": "incident_alerts", + "type": "Pipeline", + "api_version": "core/v2" + } + ] + } +] +{{< /code >}} + +{{% notice note %}} +**NOTE**: Read [API response filtering](../../#response-filtering) for more filter statement examples that demonstrate how to filter responses using different operators with label and field selectors. +{{% /notice %}} + +### API Specification + +/checks (GET) with response filters | +---------------|------ +description | Returns the list of checks that match the [response filters][5] applied in the API request. +example url | http://hostname:8080/api/core/v2/checks +pagination | This endpoint supports [pagination][4] using the `limit` and `continue` query parameters. +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "command": "check-cpu-usage.sh -w 75 -c 90", + "handlers": [], + "high_flap_threshold": 0, + "interval": 60, + "low_flap_threshold": 0, + "publish": true, + "runtime_assets": [ + "check-cpu-usage" + ], + "subscriptions": [ + "system", + "health" + ], + "proxy_entity_name": "", + "check_hooks": [ + { + "critical": [ + "process_tree" + ] + } + ], + "stdin": false, + "subdue": null, + "ttl": 0, + "timeout": 0, + "round_robin": false, + "output_metric_format": "", + "output_metric_handlers": null, + "env_vars": null, + "metadata": { + "name": "check_cpu", + "namespace": "default", + "created_by": "admin" + }, + "secrets": null, + "pipelines": [ + { + "name": "incident_alerts", + "type": "Pipeline", + "api_version": "core/v2" + } + ] + } +] +{{< /code >}} + + +[1]: ../../../observability-pipeline/observe-schedule/checks/ +[2]: ../../../observability-pipeline/observe-schedule/hooks/ +[3]: ../../../observability-pipeline/observe-schedule/checks#check-hooks-attribute +[4]: ../../#pagination +[5]: ../../#response-filtering +[6]: https://tools.ietf.org/html/rfc7396 diff --git a/content/sensu-go/6.12/api/core/cluster-role-bindings.md b/content/sensu-go/6.12/api/core/cluster-role-bindings.md new file mode 100644 index 0000000000..d8e24c9b39 --- /dev/null +++ b/content/sensu-go/6.12/api/core/cluster-role-bindings.md @@ -0,0 +1,484 @@ +--- +title: "core/v2/clusterrolebindings" +description: "Read this API documentation to learn about Sensu core/v2/clusterrolebindings API endpoints, with examples for retrieving and managing cluster role bindings." +core_api_title: "core/v2/clusterrolebindings" +type: "core_api" +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: core +--- + +{{% notice note %}} +**NOTE**: Requests to `core/v2/clusterrolebindings` API endpoints require you to authenticate with a Sensu [API key](../../#configure-an-environment-variable-for-api-key-authentication) or [access token](../../#authenticate-with-auth-api-endpoints). +The code examples in this document use the [environment variable](../../#configure-an-environment-variable-for-api-key-authentication) `$SENSU_API_KEY` to represent a valid API key in API requests. +{{% /notice %}} + +## Get all cluster role bindings + +The `/clusterrolebindings` API endpoint provides HTTP GET access to [cluster role binding][1] data. + +### Example {#clusterrolebindings-get-example} + +The following example demonstrates a GET request to the `/clusterrolebindings` API endpoint: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/core/v2/clusterrolebindings \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request results in a successful `HTTP/1.1 200 OK` response and a JSON array that contains the [cluster role binding definitions][1]: + +{{< code text >}} +[ + { + "subjects": [ + { + "type": "Group", + "name": "cluster-admins" + } + ], + "role_ref": { + "type": "ClusterRole", + "name": "cluster-admin" + }, + "metadata": { + "name": "cluster-admin", + "created_by": "admin" + } + }, + { + "subjects": [ + { + "type": "Group", + "name": "system:agents" + } + ], + "role_ref": { + "type": "ClusterRole", + "name": "system:agent" + }, + "metadata": { + "name": "system:agent", + "created_by": "admin" + } + } +] +{{< /code >}} + +### API Specification {#clusterrolebindings-get-specification} + +/clusterrolebindings (GET) | +---------------|------ +description | Returns the list of cluster role bindings. +example url | http://hostname:8080/api/core/v2/clusterrolebindings +pagination | This endpoint supports [pagination][2] using the `limit` and `continue` query parameters. +response filtering | This endpoint supports [API response filtering][3]. +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "subjects": [ + { + "type": "Group", + "name": "cluster-admins" + } + ], + "role_ref": { + "type": "ClusterRole", + "name": "cluster-admin" + }, + "metadata": { + "name": "cluster-admin", + "created_by": "admin" + } + }, + { + "subjects": [ + { + "type": "Group", + "name": "system:agents" + } + ], + "role_ref": { + "type": "ClusterRole", + "name": "system:agent" + }, + "metadata": { + "name": "system:agent" + } + } +] +{{< /code >}} + +## Create a new cluster role binding + +The `/clusterrolebindings` API endpoint provides HTTP POST access to create a [cluster role binding][1]. + +### Example {#clusterrolebindings-post-example} + +In the following example, an HTTP POST request is submitted to the `/clusterrolebindings` API endpoint to create a cluster role binding that assigns the `cluster-admin` cluster role to the user `bob`. +The request includes the cluster role binding definition in the request body, + +{{< code shell >}} +curl -X POST \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "subjects": [ + { + "type": "User", + "name": "bob" + } + ], + "role_ref": { + "type": "ClusterRole", + "name": "cluster-admin" + }, + "metadata": { + "name": "bob-binder" + } +}' \ +http://127.0.0.1:8080/api/core/v2/clusterrolebindings +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#clusterrolebindings-post-specification} + +/clusterrolebindings (POST) | +----------------|------ +description | Creates a Sensu cluster role binding. +example URL | http://hostname:8080/api/core/v2/clusterrolebindings +payload | {{< code shell >}} +{ + "subjects": [ + { + "type": "User", + "name": "bob" + } + ], + "role_ref": { + "type": "ClusterRole", + "name": "cluster-admin" + }, + "metadata": { + "name": "bob-binder" + } +} +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Get a specific cluster role binding {#clusterrolebindingsclusterrolebinding-get} + +The `/clusterrolebindings/:clusterrolebinding` API endpoint provides HTTP GET access to [cluster role binding data][1] for specific `:clusterrolebinding` definitions, by cluster role binding `name`. + +### Example {#clusterrolebindingsclusterrolebinding-get-example} + +The following example queries the `/clusterrolebindings/:clusterrolebinding` API endpoint for the `:clusterrolebinding` named `bob-binder`: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/core/v2/clusterrolebindings/bob-binder \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request will return a successful `HTTP/1.1 200 OK` response and a JSON map that contains the requested [`:clusterrolebinding` definition][1] (in this example, `bob-binder`): + +{{< code text >}} +{ + "subjects": [ + { + "type": "User", + "name": "bob" + } + ], + "role_ref": { + "type": "ClusterRole", + "name": "cluster-admin" + }, + "metadata": { + "name": "bob-binder", + "created_by": "admin" + } +} +{{< /code >}} + +### API Specification {#clusterrolebindingsclusterrolebinding-get-specification} + +/clusterrolebindings/:clusterrolebinding (GET) | +---------------------|------ +description | Returns the specified cluster role binding. +example url | http://hostname:8080/api/core/v2/clusterrolebindings/bob-binder +response type | Map +response codes |
    • **Success**: 200 (OK)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +{ + "subjects": [ + { + "type": "User", + "name": "bob" + } + ], + "role_ref": { + "type": "ClusterRole", + "name": "cluster-admin" + }, + "metadata": { + "name": "bob-binder", + "created_by": "admin" + } +} +{{< /code >}} + +## Create or update a cluster role binding {#clusterrolebindingsclusterrolebinding-put} + +The `/clusterrolebindings/:clusterrolebinding` API endpoint provides HTTP PUT access to create or update a [cluster role binding][1], by cluster role binding `name`. + +### Example {#clusterrolebindingsclusterrolebinding-put-example} + +In the following example, an HTTP PUT request is submitted to the `/clusterrolebindings/:clusterrolebinding` API endpoint to create a cluster role binding that assigns the `cluster-admin` cluster role to users in the group `ops`. +The request includes the cluster role binding definition in the request body: + +{{< code shell >}} +curl -X PUT \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "subjects": [ + { + "type": "Group", + "name": "ops" + } + ], + "role_ref": { + "type": "ClusterRole", + "name": "cluster-admin" + }, + "metadata": { + "name": "ops-group-binder" + } +}' \ +http://127.0.0.1:8080/api/core/v2/clusterrolebindings/ops-group-binder +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#clusterrolebindingsclusterrolebinding-put-specification} + +/clusterrolebindings/:clusterrolebinding (PUT) | +----------------|------ +description | Creates or updates the specified Sensu cluster role binding. +example URL | http://hostname:8080/api/core/v2/clusterrolebindings/ops-group-binder +payload | {{< code shell >}} +{ + "subjects": [ + { + "type": "Group", + "name": "ops" + } + ], + "role_ref": { + "type": "ClusterRole", + "name": "cluster-admin" + }, + "metadata": { + "name": "ops-group-binder" + } +} +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Update a cluster role binding with PATCH + +The `/clusterrolebindings/:clusterrolebinding` API endpoint provides HTTP PATCH access to update `:clusterrolebinding` definitions, specified by cluster role binding name. + +{{% notice note %}} +**NOTE**: You cannot change a resource's `name` or `namespace` with a PATCH request. +Use a [PUT request](#clusterrolebindingsclusterrolebinding-put) instead.

    +Also, you cannot add elements to an array with a PATCH request — you must replace the entire array. +{{% /notice %}} + +### Example + +In the following example, an HTTP PATCH request is submitted to the `/clusterrolebindings/:clusterrolebinding` API endpoint to update the subjects array for the `ops-group-binder` check, resulting in a `HTTP/1.1 200 OK` response and the updated cluster role binding definition. + +We support [JSON merge patches][4], so you must set the `Content-Type` header to `application/merge-patch+json` for PATCH requests. + +{{< code shell >}} +curl -X PATCH \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/merge-patch+json' \ +-d '{ + "subjects": [ + { + "type": "Group", + "name": "ops_team_1" + }, + { + "type": "Group", + "name": "ops_team_2" + } + ] +}' \ +http://127.0.0.1:8080/api/core/v2/clusterrolebindings/ops-group-binder +{{< /code >}} + +### API Specification + +/clusterrolebindings/:clusterrolebinding (PATCH) | +----------------|------ +description | Updates the specified Sensu cluster role binding. +example URL | http://hostname:8080/api/core/v2/clusterrolebindings/ops-group-binder +payload | {{< code shell >}} +{ + "subjects": [ + { + "type": "Group", + "name": "ops_team_1" + }, + { + "type": "Group", + "name": "ops_team_2" + } + ] +} +{{< /code >}} +response codes |
    • **Success**: 200 (OK)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Delete a cluster role binding {#clusterrolebindingsclusterrolebinding-delete} + +The `/clusterrolebindings/:clusterrolebinding` API endpoint provides HTTP DELETE access to delete a cluster role binding from Sensu (specified by the cluster role binding name). + +### Example {#clusterrolebindingsclusterrolebinding-delete-example} + +The following example shows a request to the `/clusterrolebindings/:clusterrolebinding` API endpoint to delete the check named `ops-binding`, which will result in a successful `HTTP/1.1 204 No Content` response: + +{{< code shell >}} +curl -X DELETE \ +-H "Authorization: Key $SENSU_API_KEY" \ +http://127.0.0.1:8080/api/core/v2/clusterrolebindings/ops-binding +{{< /code >}} + +### API Specification {#clusterrolebindingsclusterrolebinding-delete-specification} + +/clusterrolebindings/:clusterrolebinding (DELETE) | +--------------------------|------ +description | Removes a cluster role binding from Sensu (specified by the cluster role binding name). +example url | http://hostname:8080/api/core/v2/clusterrolebindings/ops-binding +response codes |
    • **Success**: 204 (No Content)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + +## Get a subset of cluster role bindings with response filtering + +The `/clusterrolebindings` API endpoint supports [response filtering][3] for a subset of cluster role binding data based on labels and the following fields: + +- `clusterrolebinding.name` +- `clusterrolebinding.role_ref.name` +- `clusterrolebinding.role_ref.type` + +### Example + +The following example demonstrates a request to the `/clusterrolebindings` API endpoint with [response filtering][3] to retrieve only [cluster role binding definitions][1] whose `role_ref.name` includes `cluster-user`: + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/clusterrolebindings -G \ +--data-urlencode 'fieldSelector="cluster-user" in clusterrolebinding.role_ref.name' +{{< /code >}} + +The example request will result in a successful `HTTP/1.1 200 OK` response and a JSON array that contains only [cluster role binding definitions][1] whose `role_ref.name` includes `cluster-user`: + +{{< code text >}} +[ + { + "subjects": [ + { + "type": "User", + "name": "ann" + } + ], + "role_ref": { + "type": "ClusterRole", + "name": "cluster-user" + }, + "metadata": { + "name": "ann-binder", + "created_by": "admin" + } + }, + { + "subjects": [ + { + "type": "User", + "name": "bonita" + } + ], + "role_ref": { + "type": "ClusterRole", + "name": "cluster-user" + }, + "metadata": { + "name": "bonita-binder", + "created_by": "admin" + } + } +] +{{< /code >}} + +{{% notice note %}} +**NOTE**: Read [API response filtering](../../#response-filtering) for more filter statement examples that demonstrate how to filter responses using different operators with label and field selectors. +{{% /notice %}} + +### API Specification + +/clusterrolebindings (GET) with response filters | +---------------|------ +description | Returns the list of cluster role bindings that match the [response filters][3] applied in the API request. +example url | http://hostname:8080/api/core/v2/clusterrolebindings +pagination | This endpoint supports [pagination][4] using the `limit` and `continue` query parameters. +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "subjects": [ + { + "type": "User", + "name": "ann" + } + ], + "role_ref": { + "type": "ClusterRole", + "name": "cluster-user" + }, + "metadata": { + "name": "ann-binder", + "created_by": "admin" + } + }, + { + "subjects": [ + { + "type": "User", + "name": "bonita" + } + ], + "role_ref": { + "type": "ClusterRole", + "name": "cluster-user" + }, + "metadata": { + "name": "bonita-binder", + "created_by": "admin" + } + } +] +{{< /code >}} + + +[1]: ../../../operations/control-access/rbac/#role-bindings-and-cluster-role-bindings +[2]: ../../#pagination +[3]: ../../#response-filtering +[4]: https://tools.ietf.org/html/rfc7396 diff --git a/content/sensu-go/6.12/api/core/cluster-roles.md b/content/sensu-go/6.12/api/core/cluster-roles.md new file mode 100644 index 0000000000..1acc4b781f --- /dev/null +++ b/content/sensu-go/6.12/api/core/cluster-roles.md @@ -0,0 +1,579 @@ +--- +title: "core/v2/clusterroles" +description: "Read this API documentation for information about Sensu core/v2/clusterroles API endpoints, with examples for retrieving and managing cluster roles." +core_api_title: "core/v2/clusterroles" +type: "core_api" +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: core +--- + +{{% notice note %}} +**NOTE**: Requests to `core/v2/clusterroles` API endpoints require you to authenticate with a Sensu [API key](../../#configure-an-environment-variable-for-api-key-authentication) or [access token](../../#authenticate-with-auth-api-endpoints). +The code examples in this document use the [environment variable](../../#configure-an-environment-variable-for-api-key-authentication) `$SENSU_API_KEY` to represent a valid API key in API requests. +{{% /notice %}} + +## Get all cluster roles + +The `/clusterroles` API endpoint provides HTTP GET access to [cluster role][1] data. + +### Example {#clusterroles-get-example} + +The following example demonstrates a GET request to the `/clusterroles` API endpoint: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/core/v2/clusterroles \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request results in a successful `HTTP/1.1 200 OK` response and a JSON array that contains the [cluster role definitions][1]: + +{{< code text >}} +[ + { + "rules": [ + { + "verbs": [ + "*" + ], + "resources": [ + "assets", + "checks", + "entities", + "extensions", + "events", + "filters", + "handlers", + "hooks", + "mutators", + "silenced", + "roles", + "rolebindings" + ], + "resource_names": null + }, + { + "verbs": [ + "get", + "list" + ], + "resources": [ + "namespaces" + ], + "resource_names": null + } + ], + "metadata": { + "name": "admin" + } + }, + { + "rules": [ + { + "verbs": [ + "*" + ], + "resources": [ + "*" + ], + "resource_names": null + } + ], + "metadata": { + "name": "cluster-admin", + "created_by": "admin" + } + } +] +{{< /code >}} + +### API Specification {#clusterroles-get-specification} + +/clusterroles (GET) | +---------------|------ +description | Returns the list of cluster roles. +example url | http://hostname:8080/api/core/v2/clusterroles +pagination | This endpoint supports [pagination][2] using the `limit` and `continue` query parameters. +response filtering | This endpoint supports [API response filtering][3]. +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "rules": [ + { + "verbs": [ + "*" + ], + "resources": [ + "assets", + "checks", + "entities", + "extensions", + "events", + "filters", + "handlers", + "hooks", + "mutators", + "silenced", + "roles", + "rolebindings" + ], + "resource_names": null + }, + { + "verbs": [ + "get", + "list" + ], + "resources": [ + "namespaces" + ], + "resource_names": null + } + ], + "metadata": { + "name": "admin" + } + }, + { + "rules": [ + { + "verbs": [ + "*" + ], + "resources": [ + "*" + ], + "resource_names": null + } + ], + "metadata": { + "name": "cluster-admin", + "created_by": "admin" + } + } +] +{{< /code >}} + +## Create a new cluster role + +The `/clusterroles` API endpoint provides HTTP POST access to create a [cluster role][1]. + +### Example {#clusterroles-post-example} + +In the following example, an HTTP POST request is submitted to the `/clusterroles` API endpoint to create a `global-event-reader` cluster role. +The request includes the cluster role definition in the request body: + +{{< code shell >}} +curl -X POST \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "metadata": { + "name": "global-event-reader" + }, + "rules": [ + { + "verbs": [ + "get", + "list" + ], + "resources": [ + "events" + ], + "resource_names": null + } + ] +}' \ +http://127.0.0.1:8080/api/core/v2/clusterroles +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#clusterroles-post-specification} + +/clusterroles (POST) | +----------------|------ +description | Creates a Sensu cluster role. +example URL | http://hostname:8080/api/core/v2/clusterroles +payload | {{< code shell >}} +{ + "metadata": { + "name": "global-event-reader" + }, + "rules": [ + { + "verbs": [ + "get", + "list" + ], + "resources": [ + "events" + ], + "resource_names": null + } + ] +} +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Get a specific cluster role {#clusterrolesclusterrole-get} + +The `/clusterroles/:clusterrole` API endpoint provides HTTP GET access to [cluster role data][1] for specific `:clusterrole` definitions, by cluster role `name`. + +### Example {#clusterrolesclusterrole-get-example} + +The following example queries the `/clusterroles/:clusterrole` API endpoint for the `:clusterrole` named `global-event-reader`: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/core/v2/clusterroles/global-event-reader \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request will return a successful `HTTP/1.1 200 OK` response and a JSON map that contains the requested [`:clusterrole` definition][1] (in this example, `global-event-reader`): + +{{< code text >}} +{ + "metadata": { + "name": "global-event-reader", + "created_by": "admin" + }, + "rules": [ + { + "verbs": [ + "get", + "list" + ], + "resources": [ + "events" + ], + "resource_names": null + } + ] +} +{{< /code >}} + +### API Specification {#clusterrolesclusterrole-get-specification} + +/clusterroles/:clusterrole (GET) | +---------------------|------ +description | Returns the specified cluster role. +example url | http://hostname:8080/api/core/v2/clusterroles/global-event-reader +response type | Map +response codes |
    • **Success**: 200 (OK)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +{ + "metadata": { + "name": "global-event-reader", + "created_by": "admin" + }, + "rules": [ + { + "verbs": [ + "get", + "list" + ], + "resources": [ + "events" + ], + "resource_names": null + } + ] +} +{{< /code >}} + +## Create or update a cluster role {#clusterrolesclusterrole-put} + +The `/clusterroles/:clusterrole` API endpoint provides HTTP PUT access to create or update a cluster role, by cluster role name. + +### Example {#clusterroles-clusterrole-put-example} + +In the following example, an HTTP PUT request is submitted to the `/clusterroles/:clusterrole` API endpoint to update the `global-event-reader` cluster role by adding `"checks"` to the resources: + +{{< code shell >}} +curl -X PUT \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "metadata": { + "name": "global-event-reader" + }, + "rules": [ + { + "verbs": [ + "get", + "list" + ], + "resources": [ + "checks", + "events" + ], + "resource_names": null + } + ] +}' \ +http://127.0.0.1:8080/api/core/v2/clusterroles +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#clusterrolesclusterrole-put-specification} + +/clusterroles/:clusterrole (PUT) | +----------------|------ +description | Creates or updates the specified Sensu cluster role. +example URL | http://hostname:8080/api/core/v2/clusterroles/global-event-reader +payload | {{< code shell >}} +{ + "metadata": { + "name": "global-event-reader" + }, + "rules": [ + { + "verbs": [ + "get", + "list" + ], + "resources": [ + "events" + ], + "resource_names": null + } + ] +} +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Update a cluster role with PATCH + +The `/clusterroles/:clusterrole` API endpoint provides HTTP PATCH access to update `:clusterrole` definitions, specified by cluster role name. + +{{% notice note %}} +**NOTE**: You cannot change a resource's `name` or `namespace` with a PATCH request. +Use a [PUT request](#clusterrolesclusterrole-put) instead.

    +Also, you cannot add elements to an array with a PATCH request — you must replace the entire array. +{{% /notice %}} + +### Example + +In the following example, an HTTP PATCH request is submitted to the `/clusterroles/:clusterrole` API endpoint to update the verbs array within the rules array for the `global-event-admin` cluster role, resulting in a `HTTP/1.1 200 OK` response and the updated check definition. + +We support [JSON merge patches][4], so you must set the `Content-Type` header to `application/merge-patch+json` for PATCH requests. + +{{< code shell >}} +curl -X PATCH \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/merge-patch+json' \ +-d '{ + "rules": [ + { + "verbs": [ + "*" + ], + "resources": [ + "events" + ], + "resource_names": null + } + ] +}' \ +http://127.0.0.1:8080/api/core/v2/clusterroles/global-event-admin +{{< /code >}} + +### API Specification + +/clusterroles/:clusterrole (PATCH) | +----------------|------ +description | Updates the specified Sensu cluster role. +example URL | http://hostname:8080/api/core/v2/clusterroles/global-event-admin +payload | {{< code shell >}} +{ + "rules": [ + { + "verbs": [ + "*" + ], + "resources": [ + "events" + ], + "resource_names": null + } + ] +} +{{< /code >}} +response codes |
    • **Success**: 200 (OK)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Delete a cluster role {#clusterrolesclusterrole-delete} + +The `/clusterroles/:clusterrole` API endpoint provides HTTP DELETE access to delete a cluster role from Sensu (specified by the cluster role name). + +### Example {#clusterrolesclusterrole-delete-example} + +The following example shows a request to the `/clusterroles/:clusterrole` API endpoint to delete the cluster role `global-event-reader`, resulting in a successful `HTTP/1.1 204 No Content` response: + +{{< code shell >}} +curl -X DELETE \ +-H "Authorization: Key $SENSU_API_KEY" \ +http://127.0.0.1:8080/api/core/v2/clusterroles/global-event-reader +{{< /code >}} + +### API Specification {#clusterrolesclusterrole-delete-specification} + +/clusterroles/:clusterrole (DELETE) | +--------------------------|------ +description | Removes a cluster role from Sensu (specified by the cluster role name). +example url | http://hostname:8080/api/core/v2/clusterroles/global-event-reader +response codes |
    • **Success**: 204 (No Content)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + +## Get a subset of cluster roles with response filtering + +The `/clusterroles` API endpoint supports [response filtering][3] for a subset of cluster role data based on labels and the `clusterrole.name` field. + +### Example + +The following example demonstrates a request to the `/clusterroles` API endpoint with [response filtering][3] for only [cluster role definitions][1] whose `clusterrole.name` includes `admin`: + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/clusterroles -G \ +--data-urlencode 'fieldSelector=clusterrole.name matches "admin"' +{{< /code >}} + +The example request will result in a successful `HTTP/1.1 200 OK` response and a JSON array that contains only [cluster role definitions][1] whose `clusterrole.name` includes `admin`: + +{{< code text >}} +[ + { + "rules": [ + { + "verbs": [ + "*" + ], + "resources": [ + "assets", + "checks", + "entities", + "events", + "filters", + "handlers", + "hooks", + "mutators", + "silenced", + "roles", + "rolebindings" + ], + "resource_names": null + }, + { + "verbs": [ + "get", + "list" + ], + "resources": [ + "namespaces" + ], + "resource_names": null + } + ], + "metadata": { + "name": "admin" + } + }, + { + "rules": [ + { + "verbs": [ + "*" + ], + "resources": [ + "*" + ], + "resource_names": null + } + ], + "metadata": { + "name": "cluster-admin" + } + } +] +{{< /code >}} + +{{% notice note %}} +**NOTE**: Read [API response filtering](../../#response-filtering) for more filter statement examples that demonstrate how to filter responses using different operators with label and field selectors. +{{% /notice %}} + +### API Specification + +/clusterroles (GET) with response filters | +---------------|------ +description | Returns the list of cluster roles that match the [response filters][3] applied in the API request. +example url | http://hostname:8080/api/core/v2/clusterroles +pagination | This endpoint supports [pagination][4] using the `limit` and `continue` query parameters. +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "rules": [ + { + "verbs": [ + "*" + ], + "resources": [ + "assets", + "checks", + "entities", + "events", + "filters", + "handlers", + "hooks", + "mutators", + "silenced", + "roles", + "rolebindings" + ], + "resource_names": null + }, + { + "verbs": [ + "get", + "list" + ], + "resources": [ + "namespaces" + ], + "resource_names": null + } + ], + "metadata": { + "name": "admin" + } + }, + { + "rules": [ + { + "verbs": [ + "*" + ], + "resources": [ + "*" + ], + "resource_names": null + } + ], + "metadata": { + "name": "cluster-admin" + } + } +] +{{< /code >}} + + +[1]: ../../../operations/control-access/rbac/#roles-and-cluster-roles +[2]: ../../#pagination +[3]: ../../#response-filtering +[4]: https://tools.ietf.org/html/rfc7396 diff --git a/content/sensu-go/6.12/api/core/cluster.md b/content/sensu-go/6.12/api/core/cluster.md new file mode 100644 index 0000000000..b135e22cb2 --- /dev/null +++ b/content/sensu-go/6.12/api/core/cluster.md @@ -0,0 +1,273 @@ +--- +title: "core/v2/cluster" +description: "Read this API documentation for information about Sensu core/v2/cluster API endpoints, with examples for retrieving and managing clusters and cluster members." +core_api_title: "core/v2/cluster" +type: "core_api" +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: core +--- + +{{% notice note %}} +**NOTE**: Requests to `core/v2/cluster` API endpoints require you to authenticate with a Sensu [API key](../../#configure-an-environment-variable-for-api-key-authentication) or [access token](../../#authenticate-with-auth-api-endpoints). +The code examples in this document use the [environment variable](../../#configure-an-environment-variable-for-api-key-authentication) `$SENSU_API_KEY` to represent a valid API key in API requests. +{{% /notice %}} + +## Get all cluster data {#clustermembers-get} + +The `/cluster/members` API endpoint provides HTTP GET access to Sensu [cluster][1] data. + +### Example {#clustermembers-get-example} + +The following example demonstrates a request to the `/cluster/members` API endpoint: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/core/v2/cluster/members \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request results in a successful `HTTP/1.1 200 OK` response and a JSON array that contains a Sensu cluster definition: + +{{< code text >}} +{ + "header": { + "cluster_id": 4255616304056076734, + "member_id": 9882886658148554927, + "raft_term": 2 + }, + "members": [ + { + "ID": 9882886658148554927, + "name": "default", + "peerURLs": [ + "http://127.0.0.1:2380" + ], + "clientURLs": [ + "http://127.0.0.1:2379" + ] + } + ] +} +{{< /code >}} + +### API Specification {#clustermembers-get-specification} + +/cluster/members (GET) | +------------------------|------ +description | Returns the etcd cluster definition. +example url | http://hostname:8080/api/core/v2/cluster/members +query parameters | `timeout`: Defines the timeout when querying etcd. Default is `3`. +response type | Map +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +example output | {{< code text >}} +{ + "header": { + "cluster_id": 4255616304056076734, + "member_id": 9882886658148554927, + "raft_term": 2 + }, + "members": [ + { + "ID": 9882886658148554927, + "name": "default", + "peerURLs": [ + "http://127.0.0.1:2380" + ], + "clientURLs": [ + "http://127.0.0.1:2379" + ] + } + ] +} +{{< /code >}} + +## Create a new cluster member {#clustermembers-post} + +The `/cluster/members` API endpoint provides HTTP POST access to create a Sensu cluster member. + +### Example {#clustermembers-post-example} + +In the following example, an HTTP POST request is submitted to the `/cluster/members` API endpoint to create a Sensu cluster member. +The request includes the cluster member peer address in the request URL: + +{{< code shell >}} +curl -X POST \ +-H "Authorization: Key $SENSU_API_KEY" \ +http://127.0.0.1:8080/api/core/v2/cluster/members?peer-addrs=http://127.0.0.1:2380 +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response along with the updated cluster definition: + +{{< code text >}} +{ + "header": { + "cluster_id": 4255616304056077000, + "member_id": 9882886658148555000, + "raft_term": 2 + }, + "members": [ + { + "ID": 9882886658148555000, + "name": "default", + "peerURLs": [ + "http://127.0.0.1:2380" + ], + "clientURLs": [ + "http://localhost:2379" + ] + } + ] +} +{{< /code >}} + +### API Specification {#clustermembers-post-specification} + +/cluster/members/:member (POST) | +----------------|------ +description | Creates a cluster member. +example url | http://hostname:8080/api/core/v2/cluster/members?peer-addrs=http://127.0.0.1:2380 +query parameters|
    • Required: `peer-addrs` (a comma-delimited list of peer addresses).
    +response codes |
    • **Success**: 200 (OK)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + +## Create or update a cluster member {#clustermembersmember-put} + +The `/cluster/members/:member` API endpoint provides HTTP PUT access to create or update a cluster member, by the cluster member's hex-encoded ID. + +### Example {#clustermembersmember-put-example} + +The following example submits an HTTP PUT request to the `/cluster/members/:member` API endpoint to update the member whose hex-encoded ID is `8927110dc66458af`. + +{{% notice warning %}} +**IMPORTANT**: The PUT `/cluster/members/:member` URL uses the cluster member's hex-encoded UInt64 ID, **not** the member ID listed in the cluster definition.

    +To get the correct hex-encoded UInt64 ID for the member, run `sensuctl cluster member-list`. +The first column in the response lists the ID you need for the PUT `/cluster/members/:member` URL. +{{% /notice %}} + +{{< code shell >}} +curl -X PUT \ +-H "Authorization: Key $SENSU_API_KEY" \ +http://127.0.0.1:8080/api/core/v2/cluster/members/8927110dc66458af?peer-addrs=http://127.0.0.1:2380 +{{< /code >}} + +The request will return a `HTTP/1.1 200 OK` response and the updated cluster definition: + +{{< code text >}} +{ + "header": { + "cluster_id": 4255616304056077000, + "member_id": 9882886658148555000, + "raft_term": 2 + }, + "members": [ + { + "ID": 9882886658148555000, + "name": "default", + "peerURLs": [ + "http://127.0.0.1:2380" + ], + "clientURLs": [ + "http://localhost:2379" + ] + } + ] +} +{{< /code >}} + +### API Specification {#clustermembersmember-put-specification} + +/cluster/members/:member (PUT) | +----------------|------ +description | Creates or updates a cluster member. +example url | http://hostname:8080/api/core/v2/cluster/members/8927110dc66458af?peer-addrs=http://127.0.0.1:2380 +url parameters | Required: Hex-encoded UInt64 cluster member ID generated using `sensuctl cluster member-list` (in this example, `8927110dc66458af`). +query parameters| Required: `peer-addrs` (a comma-delimited list of peer addresses). +response codes |
    • **Success**: 200 (OK)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    +example output | {{< code text >}} +{ + "header": { + "cluster_id": 4255616304056077000, + "member_id": 9882886658148555000, + "raft_term": 2 + }, + "members": [ + { + "ID": 9882886658148555000, + "name": "default", + "peerURLs": [ + "http://127.0.0.1:2380" + ], + "clientURLs": [ + "http://localhost:2379" + ] + } + ] +} +{{< /code >}} + +## Delete a cluster member {#clustermembersmember-delete} + +The `/cluster/members/:member` API endpoint provides HTTP DELETE access to remove a Sensu cluster member. + +### Example {#clustermembersmember-delete-example} + +The following example shows a request to the `/cluster/members/:member` API endpoint to remove the Sensu cluster member with the ID `8927110dc66458af`, which will result in a successful `HTTP/1.1 204 No Content` response. + +{{% notice warning %}} +**IMPORTANT**: The DELETE `/cluster/members/:member` URL uses the cluster member's hex-encoded UInt64 ID, **not** the member ID listed in the cluster definition.

    +To get the correct hex-encoded UInt64 ID for the member, run `sensuctl cluster member-list`. +The first column in the response lists the ID you need for the DELETE `/cluster/members/:member` URL. +{{% /notice %}} + +{{< code shell >}} +curl -X DELETE \ +-H "Authorization: Key $SENSU_API_KEY" \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/cluster/members/8927110dc66458af +{{< /code >}} + +### API Specification {#clustermembersmember-delete-specification} + +/cluster/members/:member (DELETE) | +--------------------------|------ +description | Removes a member from a Sensu cluster (specified by the member ID). +example url | http://hostname:8080/api/core/v2/cluster/members/8927110dc66458af +url parameters | Required: Hex-encoded UInt64 cluster member ID generated using `sensuctl cluster member-list` (in this example, `8927110dc66458af`) +response codes |
    • **Success**: 204 (No Content)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + +## Get a cluster ID {#clusterid-get} + +The `/cluster/id` API endpoint provides HTTP GET access to the Sensu cluster ID. + +### Example {#clusterid-get-example} + +The following example demonstrates a request to the `/cluster/id` API endpoint: + +{{< code shell >}} +curl -X GET \ + -H "Authorization: Key $SENSU_API_KEY" \ +http://127.0.0.1:8080/api/core/v2/cluster/id +{{< /code >}} + +The request will return an `HTTP/1.1 200 OK` response and a string that contains the Sensu cluster ID: + +{{< code text >}} +"23481e76-5844-4d07-b714-6e2ffbbf9315" +{{< /code >}} + +### API Specification {#clusterid-get-specification} + +/cluster/id (GET) | | +------------------|------ +description | Returns the unique Sensu cluster ID. +example url | http://hostname:8080/api/core/v2/cluster/id +query parameters | `timeout`: Defines the timeout when querying etcd. Default is `3`. +response type | String +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +example output | {{< code text >}} +"23481e76-5844-4d07-b714-6e2ffbbf9315" +{{< /code >}} + + +[1]: ../../../operations/deploy-sensu/cluster-sensu/ diff --git a/content/sensu-go/6.12/api/core/entities.md b/content/sensu-go/6.12/api/core/entities.md new file mode 100644 index 0000000000..0a4420b74b --- /dev/null +++ b/content/sensu-go/6.12/api/core/entities.md @@ -0,0 +1,932 @@ +--- +title: "core/v2/entities" +description: "Read this API documentation for information about Sensu core/v2/entities API endpoints, with examples for retrieving and managing entities." +core_api_title: "core/v2/entities" +type: "core_api" +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: core +--- + +{{% notice note %}} +**NOTE**: Requests to `core/v2/entities` API endpoints require you to authenticate with a Sensu [API key](../../#configure-an-environment-variable-for-api-key-authentication) or [access token](../../#authenticate-with-auth-api-endpoints). +The code examples in this document use the [environment variable](../../#configure-an-environment-variable-for-api-key-authentication) `$SENSU_API_KEY` to represent a valid API key in API requests. +{{% /notice %}} + +## Get all entities + +The `/entities` API endpoint provides HTTP GET access to [entity][1] data. + +### Example {#entities-get-example} + +The following example demonstrates a GET request to the `/entities` API endpoint: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/entities \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request results in a successful `HTTP/1.1 200 OK` response and a JSON array that contains the [entity definitions][1] in the `default` namespace: + +{{< code text >}} +[ + { + "entity_class": "agent", + "sensu_agent_version": "1.0.0", + "system": { + "hostname": "sensu-centos", + "os": "linux", + "platform": "centos", + "platform_family": "rhel", + "platform_version": "7.4.1708", + "network": { + "interfaces": [ + { + "name": "lo", + "addresses": [ + "127.0.0.1/8", + "::1/128" + ] + }, + { + "name": "enp0s3", + "mac": "08:00:27:11:ad:d2", + "addresses": [ + "10.0.2.15/24", + "fe80::f50c:b029:30a5:3e26/64" + ] + }, + { + "name": "enp0s8", + "mac": "08:00:27:9f:5d:f3", + "addresses": [ + "172.28.128.3/24", + "fe80::a00:27ff:fe9f:5df3/64" + ] + } + ] + }, + "arch": "amd64", + "libc_type": "glibc", + "vm_system": "kvm", + "vm_role": "host", + "cloud_provider": "", + "processes": [ + { + "name": "Slack", + "pid": 1349, + "ppid": 0, + "status": "Ss", + "background": true, + "running": true, + "created": 1582137786, + "memory_percent": 1.09932518, + "cpu_percent": 0.3263987595984941 + }, + { + "name": "Slack Helper", + "pid": 1360, + "ppid": 1349, + "status": "Ss", + "background": true, + "running": true, + "created": 1582137786, + "memory_percent": 0.146866455, + "cpu_percent": 0.308976181461092553 + } + ] + }, + "subscriptions": [ + "entity:sensu-centos" + ], + "last_seen": 1543349936, + "deregister": false, + "deregistration": {}, + "user": "agent", + "redact": [ + "password", + "passwd", + "pass", + "api_key", + "api_token", + "access_key", + "secret_key", + "private_key", + "secret" + ], + "metadata": { + "name": "sensu-centos", + "namespace": "default", + "created_by": "admin", + "labels": null, + "annotations": null + } + } +] +{{< /code >}} + +### API Specification {#entities-get-specification} + +/entities (GET) | +---------------|------ +description | Returns the list of entities. +example url | http://hostname:8080/api/core/v2/namespaces/default/entities +pagination | This endpoint supports [pagination][2] using the `limit` and `continue` query parameters. +response filtering | This endpoint supports [API response filtering][3]. +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "entity_class": "agent", + "sensu_agent_version": "1.0.0", + "system": { + "hostname": "sensu-centos", + "os": "linux", + "platform": "centos", + "platform_family": "rhel", + "platform_version": "7.4.1708", + "network": { + "interfaces": [ + { + "name": "lo", + "addresses": [ + "127.0.0.1/8", + "::1/128" + ] + }, + { + "name": "enp0s3", + "mac": "08:00:27:11:ad:d2", + "addresses": [ + "10.0.2.15/24", + "fe80::f50c:b029:30a5:3e26/64" + ] + }, + { + "name": "enp0s8", + "mac": "08:00:27:9f:5d:f3", + "addresses": [ + "172.28.128.3/24", + "fe80::a00:27ff:fe9f:5df3/64" + ] + } + ] + }, + "arch": "amd64", + "libc_type": "glibc", + "vm_system": "kvm", + "vm_role": "host", + "cloud_provider": "", + "processes": [ + { + "name": "Slack", + "pid": 1349, + "ppid": 0, + "status": "Ss", + "background": true, + "running": true, + "created": 1582137786, + "memory_percent": 1.09932518, + "cpu_percent": 0.3263987595984941 + }, + { + "name": "Slack Helper", + "pid": 1360, + "ppid": 1349, + "status": "Ss", + "background": true, + "running": true, + "created": 1582137786, + "memory_percent": 0.146866455, + "cpu_percent": 0.308976181461092553 + } + ] + }, + "subscriptions": [ + "entity:sensu-centos" + ], + "last_seen": 1543349936, + "deregister": false, + "deregistration": {}, + "user": "agent", + "redact": [ + "password", + "passwd", + "pass", + "api_key", + "api_token", + "access_key", + "secret_key", + "private_key", + "secret" + ], + "metadata": { + "name": "sensu-centos", + "namespace": "default", + "created_by": "admin", + "labels": null, + "annotations": null + } + } +] +{{< /code >}} + +## Create a new entity + +The `/entities` API endpoint provides HTTP POST access to create a Sensu entity. + +### Example {#entities-post-example} + +In the following example, an HTTP POST request is submitted to the `/entities` API endpoint to create a proxy entity named `sensu-centos`. +The request includes the entity definition in the request body: + +{{< code shell >}} +curl -X POST \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "entity_class": "proxy", + "sensu_agent_version": "1.0.0", + "subscriptions": [ + "web" + ], + "deregister": false, + "deregistration": {}, + "metadata": { + "name": "sensu-centos", + "namespace": "default", + "labels": null, + "annotations": null + } +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/entities +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#entities-post-specification} + +/entities (POST) | +----------------|------ +description | Creates a Sensu entity. +example URL | http://hostname:8080/api/core/v2/namespaces/default/entities +payload | {{< code shell >}} +{ + "entity_class": "proxy", + "sensu_agent_version": "1.0.0", + "subscriptions": [ + "web" + ], + "deregister": false, + "deregistration": {}, + "metadata": { + "name": "sensu-centos", + "namespace": "default", + "labels": null, + "annotations": null + } +} +{{< /code >}} +response codes |
    • **Success**: 200 (OK)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Get a specific entity + +The `/entities/:entity` API endpoint provides HTTP GET access to [entity data][1] for specific `:entity` definitions, by entity `name`. + +### Example {#entitiesentity-get-example} + +The following example queries the `/entities/:entity` API endpoint for the `:entity` named `sensu-centos`: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/entities/sensu-centos \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request will return a successful `HTTP/1.1 200 OK` response and a JSON map that contains the requested [`:entity` definition][1] (in this example, `sensu-centos`): + +{{< code text >}} +{ + "entity_class": "agent", + "sensu_agent_version": "1.0.0", + "system": { + "hostname": "sensu-centos", + "os": "linux", + "platform": "centos", + "platform_family": "rhel", + "platform_version": "7.4.1708", + "network": { + "interfaces": [ + { + "name": "lo", + "addresses": [ + "127.0.0.1/8", + "::1/128" + ] + }, + { + "name": "enp0s3", + "mac": "08:00:27:11:ad:d2", + "addresses": [ + "10.0.2.15/24", + "fe80::f50c:b029:30a5:3e26/64" + ] + }, + { + "name": "enp0s8", + "mac": "08:00:27:9f:5d:f3", + "addresses": [ + "172.28.128.3/24", + "fe80::a00:27ff:fe9f:5df3/64" + ] + } + ] + }, + "arch": "amd64", + "libc_type": "glibc", + "vm_system": "kvm", + "vm_role": "host", + "cloud_provider": "", + "processes": [ + { + "name": "Slack", + "pid": 1349, + "ppid": 0, + "status": "Ss", + "background": true, + "running": true, + "created": 1582137786, + "memory_percent": 1.09932518, + "cpu_percent": 0.3263987595984941 + }, + { + "name": "Slack Helper", + "pid": 1360, + "ppid": 1349, + "status": "Ss", + "background": true, + "running": true, + "created": 1582137786, + "memory_percent": 0.146866455, + "cpu_percent": 0.308976181461092553 + } + ] + }, + "subscriptions": [ + "entity:sensu-centos" + ], + "last_seen": 1543349936, + "deregister": false, + "deregistration": {}, + "user": "agent", + "redact": [ + "password", + "passwd", + "pass", + "api_key", + "api_token", + "access_key", + "secret_key", + "private_key", + "secret" + ], + "metadata": { + "name": "sensu-centos", + "namespace": "default", + "created_by": "admin", + "labels": null, + "annotations": null + } +} +{{< /code >}} + +### API Specification {#entitiesentity-get-specification} + +/entities/:entity (GET) | +---------------------|------ +description | Returns the specified entity. +example url | http://hostname:8080/api/core/v2/namespaces/default/entities/sensu-centos +response type | Map +response codes |
    • **Success**: 200 (OK)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +{ + "entity_class": "agent", + "sensu_agent_version": "1.0.0", + "system": { + "hostname": "sensu-centos", + "os": "linux", + "platform": "centos", + "platform_family": "rhel", + "platform_version": "7.4.1708", + "network": { + "interfaces": [ + { + "name": "lo", + "addresses": [ + "127.0.0.1/8", + "::1/128" + ] + }, + { + "name": "enp0s3", + "mac": "08:00:27:11:ad:d2", + "addresses": [ + "10.0.2.15/24", + "fe80::f50c:b029:30a5:3e26/64" + ] + }, + { + "name": "enp0s8", + "mac": "08:00:27:9f:5d:f3", + "addresses": [ + "172.28.128.3/24", + "fe80::a00:27ff:fe9f:5df3/64" + ] + } + ] + }, + "arch": "amd64", + "libc_type": "glibc", + "vm_system": "kvm", + "vm_role": "host", + "cloud_provider": "", + "processes": [ + { + "name": "Slack", + "pid": 1349, + "ppid": 0, + "status": "Ss", + "background": true, + "running": true, + "created": 1582137786, + "memory_percent": 1.09932518, + "cpu_percent": 0.3263987595984941 + }, + { + "name": "Slack Helper", + "pid": 1360, + "ppid": 1349, + "status": "Ss", + "background": true, + "running": true, + "created": 1582137786, + "memory_percent": 0.146866455, + "cpu_percent": 0.308976181461092553 + } + ] + }, + "subscriptions": [ + "entity:sensu-centos" + ], + "last_seen": 1543349936, + "deregister": false, + "deregistration": {}, + "user": "agent", + "redact": [ + "password", + "passwd", + "pass", + "api_key", + "api_token", + "access_key", + "secret_key", + "private_key", + "secret" + ], + "metadata": { + "name": "sensu-centos", + "namespace": "default", + "created_by": "admin", + "labels": null, + "annotations": null + } +} +{{< /code >}} + +## Create or update an entity {#entitiesentity-put} + +{{% notice note %}} +**NOTE**: This endpoint will not update [agent-managed entities](../../../observability-pipeline/observe-entities/entities/#manage-agent-entities-via-the-agent). +Requests to update agent-managed entities via the Sensu backend REST API will fail and return `HTTP 409 Conflict`. +{{% /notice %}} + +The `/entities/:entity` API endpoint provides HTTP PUT access to create or update the specified Sensu entity. + +### Example {#entitiesentity-put-example} + +In the following example, an HTTP PUT request is submitted to the `/entities/:entity` API endpoint to update the entity named `sensu-centos`. +The request includes the updated entity definition in the request body: + +{{< code shell >}} +curl -X PUT \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "entity_class": "proxy", + "sensu_agent_version": "1.0.0", + "subscriptions": [ + "web", + "system" + ], + "deregister": false, + "deregistration": {}, + "metadata": { + "name": "sensu-centos", + "namespace": "default", + "labels": null, + "annotations": null + } +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/entities/sensu-centos +{{< /code >}} + +The request will return a successful `HTTP/1.1 200 OK` response and a JSON map that contains the updated entity definition: + +{{< code text >}} +{ + "entity_class": "proxy", + "system": { + "network": { + "interfaces": null + }, + "libc_type": "", + "vm_system": "", + "vm_role": "", + "cloud_provider": "", + "processes": null + }, + "subscriptions": [ + "web", + "system" + ], + "last_seen": 0, + "deregister": false, + "deregistration": {}, + "metadata": { + "name": "sensu-centos", + "namespace": "default" + }, + "sensu_agent_version": "1.0.0" +} +{{< /code >}} + +### API Specification {#entitiesentity-put-specification} + +/entities/:entity (PUT) | +----------------|------ +description | Creates or updates the specified Sensu entity. {{% notice note %}} +**NOTE**: When you create an entity via an HTTP PUT request, the entity will use the namespace in the request URL. +{{% /notice %}} +example URL | http://hostname:8080/api/core/v2/namespaces/default/entities/sensu-centos +payload | {{< code shell >}} +{ + "entity_class": "proxy", + "sensu_agent_version": "1.0.0", + "subscriptions": [ + "web", + "system" + ], + "deregister": false, + "deregistration": {}, + "metadata": { + "name": "sensu-centos", + "namespace": "default", + "labels": null, + "annotations": null + } +} +{{< /code >}} +response codes |
    • **Success**: 200 (OK)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Update an entity with PATCH + +{{% notice note %}} +**NOTE**: This endpoint will not update [agent-managed entities](../../../observability-pipeline/observe-entities/entities/#manage-agent-entities-via-the-agent). +Requests to update agent-managed entities via the Sensu backend REST API will fail and return `HTTP 409 Conflict`. +{{% /notice %}} + +The `/entities/:entity` API endpoint provides HTTP PATCH access to update **entity configuration attributes** in `:entity` definitions, specified by entity name: + +- `labels` +- `annotations` +- `created_by` +- `entity_class` +- `user` +- `subscriptions` +- `deregister` +- `deregistration` +- `redact` +- `keepalive_handler` + +{{% notice note %}} +**NOTE**: You cannot change a resource's `name` or `namespace` with a PATCH request. +Use a [PUT request](#entitiesentity-put) instead.

    +Also, you cannot add elements to an array with a PATCH request — you must replace the entire array. +{{% /notice %}} + +### Example + +In the following example, an HTTP PATCH request is submitted to the `/entities/:entity` API endpoint to add a label for the `sensu-centos` entity, resulting in a `HTTP/1.1 200 OK` response and the updated entity definition. + +We support [JSON merge patches][4], so you must set the `Content-Type` header to `application/merge-patch+json` for PATCH requests. + +{{< code shell >}} +curl -X PATCH \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/merge-patch+json' \ +-d '{ + "metadata": { + "labels": { + "region": "us-west-1" + } + } +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/entities/sensu-centos +{{< /code >}} + +### API Specification + +/entities/:entity (PATCH) | +----------------|------ +description | Updates the specified Sensu entity. +example URL | http://hostname:8080/api/core/v2/namespaces/default/entities/sensu-centos +payload | {{< code shell >}} +{ + "metadata": { + "labels": { + "region": "us-west-1" + } + } +} +{{< /code >}} +response codes |
    • **Success**: 200 (OK)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Delete an entity {#entitiesentity-delete} + +The `/entities/:entity` API endpoint provides HTTP DELETE access to delete an entity from Sensu (specified by the entity name). + +### Example {#entitiesentity-delete-example} + +The following example shows a request to the `/entities/:entity` API endpoint to delete the entity `sensu-centos`, which will result in a successful `HTTP/1.1 204 No Content` response: + +{{< code shell >}} +curl -X DELETE \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/entities/sensu-centos \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +### API Specification {#entitiesentity-delete-specification} + +/entities/:entity (DELETE) | +--------------------------|------ +description | Removes a entity from Sensu (specified by the entity name). +example url | http://hostname:8080/api/core/v2/namespaces/default/entities/sensu-centos +response codes |
    • **Success**: 204 (No Content)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + +## Get a subset of entities with response filtering + +The `/entities` API endpoint supports [response filtering][3] for a subset of entity data based on labels and the following fields: + +- `entity.name` +- `entity.namespace` +- `entity.deregister` +- `entity.entity_class` +- `entity.subscriptions` + +### Example + +The following example demonstrates a request to the `/entities` API endpoint with [response filtering][3] for only [entity definitions][1] whose subscriptions include `linux`: + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/entities -G \ +--data-urlencode 'fieldSelector="linux" in entity.subscriptions' +{{< /code >}} + +The example request will result in a successful `HTTP/1.1 200 OK` response and a JSON array that contains only [entity definitions][1] whose subscriptions include `linux`: + +{{< code text >}} +[ + { + "entity_class": "agent", + "system": { + "network": { + "interfaces": null + }, + "libc_type": "", + "vm_system": "", + "vm_role": "", + "cloud_provider": "", + "processes": null + }, + "subscriptions": [ + "linux", + "entity:datastore01" + ], + "last_seen": 0, + "deregister": false, + "deregistration": {}, + "metadata": { + "name": "datastore01", + "namespace": "default", + "labels": { + "region": "us-west-1", + "service_type": "datastore", + "sensu.io/managed_by": "sensuctl" + } + }, + "sensu_agent_version": "" + }, + { + "entity_class": "agent", + "system": { + "hostname": "sensu-centos", + "os": "linux", + "platform": "centos", + "platform_family": "rhel", + "platform_version": "7.5.1804", + "network": { + "interfaces": [ + { + "name": "lo", + "addresses": [ + "127.0.0.1/8", + "::1/128" + ] + }, + { + "name": "eth0", + "mac": "08:00:27:8b:c9:3f", + "addresses": [ + "10.0.2.15/24", + "fe80::c68e:8fd8:32f0:7c5d/64" + ] + }, + { + "name": "eth1", + "mac": "08:00:27:3b:a9:9f", + "addresses": [ + "192.168.56.23/24", + "fe80::a00:27ff:fe3b:a99f/64" + ] + } + ] + }, + "arch": "amd64", + "libc_type": "glibc", + "vm_system": "vbox", + "vm_role": "guest", + "cloud_provider": "", + "processes": null + }, + "subscriptions": [ + "linux", + "entity:sensu-centos" + ], + "last_seen": 1644615964, + "deregister": false, + "deregistration": {}, + "user": "agent", + "redact": [ + "password", + "passwd", + "pass", + "api_key", + "api_token", + "access_key", + "secret_key", + "private_key", + "secret" + ], + "metadata": { + "name": "sensu-centos", + "namespace": "default" + }, + "sensu_agent_version": "6.6.5" + } +] +{{< /code >}} + +{{% notice note %}} +**NOTE**: Read [API response filtering](../../#response-filtering) for more filter statement examples that demonstrate how to filter responses using different operators with label and field selectors. +{{% /notice %}} + +### API Specification + +/entities (GET) with response filters | +---------------|------ +description | Returns the list of entities that match the [response filters][3] applied in the API request. +example url | http://hostname:8080/api/core/v2/entities +pagination | This endpoint supports [pagination][4] using the `limit` and `continue` query parameters. +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "entity_class": "agent", + "system": { + "network": { + "interfaces": null + }, + "libc_type": "", + "vm_system": "", + "vm_role": "", + "cloud_provider": "", + "processes": null + }, + "subscriptions": [ + "linux", + "entity:datastore01" + ], + "last_seen": 0, + "deregister": false, + "deregistration": {}, + "metadata": { + "name": "datastore01", + "namespace": "default", + "labels": { + "region": "us-west-1", + "service_type": "datastore", + "sensu.io/managed_by": "sensuctl" + } + }, + "sensu_agent_version": "" + }, + { + "entity_class": "agent", + "system": { + "hostname": "sensu-centos", + "os": "linux", + "platform": "centos", + "platform_family": "rhel", + "platform_version": "7.5.1804", + "network": { + "interfaces": [ + { + "name": "lo", + "addresses": [ + "127.0.0.1/8", + "::1/128" + ] + }, + { + "name": "eth0", + "mac": "08:00:27:8b:c9:3f", + "addresses": [ + "10.0.2.15/24", + "fe80::c68e:8fd8:32f0:7c5d/64" + ] + }, + { + "name": "eth1", + "mac": "08:00:27:3b:a9:9f", + "addresses": [ + "192.168.56.23/24", + "fe80::a00:27ff:fe3b:a99f/64" + ] + } + ] + }, + "arch": "amd64", + "libc_type": "glibc", + "vm_system": "vbox", + "vm_role": "guest", + "cloud_provider": "", + "processes": null + }, + "subscriptions": [ + "linux", + "entity:sensu-centos" + ], + "last_seen": 1644615964, + "deregister": false, + "deregistration": {}, + "user": "agent", + "redact": [ + "password", + "passwd", + "pass", + "api_key", + "api_token", + "access_key", + "secret_key", + "private_key", + "secret" + ], + "metadata": { + "name": "sensu-centos", + "namespace": "default" + }, + "sensu_agent_version": "6.6.5" + } +] +{{< /code >}} + + +[1]: ../../../observability-pipeline/observe-entities/entities/ +[2]: ../../#pagination +[3]: ../../#response-filtering +[4]: https://tools.ietf.org/html/rfc7396 diff --git a/content/sensu-go/6.12/api/core/events.md b/content/sensu-go/6.12/api/core/events.md new file mode 100644 index 0000000000..afc6084ecb --- /dev/null +++ b/content/sensu-go/6.12/api/core/events.md @@ -0,0 +1,2122 @@ +--- +title: "core/v2/events" +description: "Read this API documentation for information about Sensu core/v2/events API endpoints, with examples for retrieving and managing events." +core_api_title: "core/v2/events" +type: "core_api" +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: core +--- + +{{% notice protip %}} +**PRO TIP**: The `core/v2/events` API endpoints are primarily designed to provide HTTP access to event data created by agent-executed checks. +To test your Sensu observability pipeline, use the [agent API](../../../observability-pipeline/observe-schedule/agent/#create-observability-events-using-the-agent-api) to create new ad hoc events or [sensuctl](../../../sensuctl/create-manage-resources/#execute-a-check-on-demand) or the [web UI](../../../web-ui/view-manage-resources/#manage-configuration-resources) to execute existing checks on demand. +{{% /notice %}} + +{{% notice note %}} +**NOTE**: Requests to `core/v2/events` API endpoints require you to authenticate with a Sensu [API key](../../#configure-an-environment-variable-for-api-key-authentication) or [access token](../../#authenticate-with-auth-api-endpoints). +The code examples in this document use the [environment variable](../../#configure-an-environment-variable-for-api-key-authentication) `$SENSU_API_KEY` to represent a valid API key in API requests. +{{% /notice %}} + +## Get all events + +The `/events` API endpoint provides HTTP GET access to [event][1] data. + +### Example {#events-get-example} + +The following example demonstrates a request to the `/events` API endpoint, resulting in a JSON array that contains [event definitions][1]. + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/events \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request results in a successful `HTTP/1.1 200 OK` response and a JSON array that contains the [event definitions][1] in the `default` namespace: + +{{< code text >}} +[ + { + "check": { + "command": "check-cpu-usage -w 75 -c 90", + "handlers": [], + "high_flap_threshold": 0, + "interval": 60, + "low_flap_threshold": 0, + "publish": true, + "runtime_assets": [ + "check-cpu-usage" + ], + "subscriptions": [ + "system" + ], + "proxy_entity_name": "", + "check_hooks": null, + "stdin": false, + "subdue": null, + "ttl": 0, + "timeout": 0, + "round_robin": false, + "duration": 5.052973881, + "executed": 1620313661, + "history": [ + { + "status": 0, + "executed": 1620313601 + }, + { + "status": 0, + "executed": 1620313661 + } + ], + "issued": 1620313661, + "output": "CheckCPU TOTAL OK: total=0.2 user=0.2 nice=0.0 system=0.0 idle=99.8 iowait=0.0 irq=0.0 softirq=0.0 steal=0.0 guest=0.0 guest_nice=0.0\n", + "state": "passing", + "status": 0, + "total_state_change": 0, + "last_ok": 1620313661, + "occurrences": 2, + "occurrences_watermark": 2, + "output_metric_format": "", + "output_metric_handlers": null, + "env_vars": null, + "metadata": { + "name": "check_cpu", + "namespace": "default" + }, + "secrets": null, + "is_silenced": false, + "processed_by": "server1", + "scheduler": "memory" + }, + "entity": { + "entity_class": "agent", + "system": { + "hostname": "server1", + "os": "linux", + "platform": "centos", + "platform_family": "rhel", + "platform_version": "7.5.1804", + "network": { + "interfaces": [ + { + "name": "lo", + "addresses": [ + "127.0.0.1/8", + "::1/128" + ] + }, + { + "name": "eth0", + "mac": "08:00:27:8b:c9:3f", + "addresses": [ + "10.0.2.15/24", + "fe80::bc00:e2c8:1059:3868/64" + ] + }, + { + "name": "eth1", + "mac": "08:00:27:73:87:93", + "addresses": [ + "172.28.128.57/24", + "fe80::a00:27ff:fe73:8793/64" + ] + } + ] + }, + "arch": "amd64", + "libc_type": "glibc", + "vm_system": "vbox", + "vm_role": "guest", + "cloud_provider": "", + "processes": null + }, + "subscriptions": [ + "system", + "entity:server1" + ], + "last_seen": 1620313661, + "deregister": false, + "deregistration": {}, + "user": "agent", + "redact": [ + "password", + "passwd", + "pass", + "api_key", + "api_token", + "access_key", + "secret_key", + "private_key", + "secret" + ], + "metadata": { + "name": "server1", + "namespace": "default" + }, + "sensu_agent_version": "6.2.7" + }, + "pipelines": [ + { + "api_version": "core/v2", + "type": "Pipeline", + "name": "incident_alerts" + } + ], + "id": "da53be74-be42-4862-a481-b7e3236e8e6d", + "metadata": { + "namespace": "default" + }, + "sequence": 3, + "timestamp": 1620313666 + } +] +{{< /code >}} + +### API Specification {#events-get-specification} + +/events (GET) | +---------------|------ +description | Returns the list of events. +example url | http://hostname:8080/api/core/v2/namespaces/default/events +pagination | This endpoint supports [pagination][2] using the `limit` and `continue` query parameters. +response filtering | This endpoint supports [API response filtering][10]. +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "check": { + "command": "check-cpu-usage -w 75 -c 90", + "handlers": [], + "high_flap_threshold": 0, + "interval": 60, + "low_flap_threshold": 0, + "publish": true, + "runtime_assets": [ + "check-cpu-usage" + ], + "subscriptions": [ + "system" + ], + "proxy_entity_name": "", + "check_hooks": null, + "stdin": false, + "subdue": null, + "ttl": 0, + "timeout": 0, + "round_robin": false, + "duration": 5.052973881, + "executed": 1620313661, + "history": [ + { + "status": 0, + "executed": 1620313601 + }, + { + "status": 0, + "executed": 1620313661 + } + ], + "issued": 1620313661, + "output": "CheckCPU TOTAL OK: total=0.2 user=0.2 nice=0.0 system=0.0 idle=99.8 iowait=0.0 irq=0.0 softirq=0.0 steal=0.0 guest=0.0 guest_nice=0.0\n", + "state": "passing", + "status": 0, + "total_state_change": 0, + "last_ok": 1620313661, + "occurrences": 2, + "occurrences_watermark": 2, + "output_metric_format": "", + "output_metric_handlers": null, + "env_vars": null, + "metadata": { + "name": "check_cpu", + "namespace": "default" + }, + "secrets": null, + "is_silenced": false, + "processed_by": "server1", + "scheduler": "memory" + }, + "entity": { + "entity_class": "agent", + "system": { + "hostname": "server1", + "os": "linux", + "platform": "centos", + "platform_family": "rhel", + "platform_version": "7.5.1804", + "network": { + "interfaces": [ + { + "name": "lo", + "addresses": [ + "127.0.0.1/8", + "::1/128" + ] + }, + { + "name": "eth0", + "mac": "08:00:27:8b:c9:3f", + "addresses": [ + "10.0.2.15/24", + "fe80::bc00:e2c8:1059:3868/64" + ] + }, + { + "name": "eth1", + "mac": "08:00:27:73:87:93", + "addresses": [ + "172.28.128.57/24", + "fe80::a00:27ff:fe73:8793/64" + ] + } + ] + }, + "arch": "amd64", + "libc_type": "glibc", + "vm_system": "vbox", + "vm_role": "guest", + "cloud_provider": "", + "processes": null + }, + "subscriptions": [ + "system", + "entity:server1" + ], + "last_seen": 1620313661, + "deregister": false, + "deregistration": {}, + "user": "agent", + "redact": [ + "password", + "passwd", + "pass", + "api_key", + "api_token", + "access_key", + "secret_key", + "private_key", + "secret" + ], + "metadata": { + "name": "server1", + "namespace": "default" + }, + "sensu_agent_version": "6.2.7" + }, + "pipelines": [ + { + "api_version": "core/v2", + "type": "Pipeline", + "name": "incident_alerts" + } + ], + "id": "da53be74-be42-4862-a481-b7e3236e8e6d", + "metadata": { + "namespace": "default" + }, + "sequence": 3, + "timestamp": 1620313666 + } +] +{{< /code >}} + +## Create a new event + +The `/events` API endpoint provides HTTP POST access to create an event and send it to the Sensu observability pipeline. + +### Example {#events-post-example} + +In the following example, an HTTP POST request is submitted to the `/events` API endpoint to create an event. +The request includes information about the check and entity represented by the event: + +{{< code shell >}} +curl -X POST \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "entity": { + "entity_class": "proxy", + "metadata": { + "name": "server1", + "namespace": "default" + } + }, + "check": { + "output": "Server error", + "state": "failing", + "status": 2, + "interval": 60, + "metadata": { + "name": "server-health" + } + }, + "pipelines": [ + { + "api_version": "core/v2", + "type": "Pipeline", + "name": "incident_alerts" + } + ] +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/events +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +To create useful, actionable events, we recommend using check attributes like `status` (`0` for OK, `1` for warning, `2` for critical) and `output`, as well as adding `pipelines`, as shown in this example. +For more information about event attributes and their available values, read the [event specification][8]. + +For events created with this endpoint, the following attributes have the default value `0` unless you specify a different value for testing: + +- `executed` +- `issued` +- `last_seen` +- `status` + +The `last_ok` attribute will default to `0` even if you manually specify OK status in the request body. + +The `sensu_agent_version` attribute will return with a null value for events created with this endpoint because these events are not created by an agent-executed check. + +### API Specification {#events-post-specification} + +/events (POST) | +----------------|------ +description | Creates a new Sensu event. To update an existing event, use the [`/events` PUT endpoint][11].

    If you create a new event that references an entity that does not already exist, sensu-backend will automatically create a proxy entity in the same namespace when the event is published.

    If you create an event that references an existing entity but includes different information for entity attributes, Sensu **will not** make any changes to the existing entity's definition based on the event you create via the API.{{% notice note %}}**NOTE**: An agent cannot belong to, execute checks in, or create events in more than one namespace. +{{% /notice %}} +example URL | http://hostname:8080/api/core/v2/namespaces/default/events +payload | {{< code shell >}} +{ + "entity": { + "entity_class": "proxy", + "metadata": { + "name": "server1", + "namespace": "default" + } + }, + "check": { + "output": "Server error", + "state": "failing", + "status": 2, + "interval": 60, + "metadata": { + "name": "server-health" + } + }, + "pipelines": [ + { + "api_version": "core/v2", + "type": "Pipeline", + "name": "incident_alerts" + } + ] +} +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Get event data for a specific entity {#eventsentity-get} + +The `/events/:entity` API endpoint provides HTTP GET access to [event data][1] specific to an `:entity`, by entity `name`. + +### Example {#eventsentity-get-example} + +The following example queries the `/events/:entity` API endpoint for Sensu events for the `server1` entity: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/events/server1 \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request will return a successful `HTTP/1.1 200 OK` response and a JSON map that contains the Sensu events for the `server1` entity: + +{{< code text >}} +[ + { + "check": { + "command": "check-cpu-usage -w 75 -c 90", + "handlers": [], + "high_flap_threshold": 0, + "interval": 60, + "low_flap_threshold": 0, + "publish": true, + "runtime_assets": [ + "check-cpu-usage" + ], + "subscriptions": [ + "system" + ], + "proxy_entity_name": "", + "check_hooks": null, + "stdin": false, + "subdue": null, + "ttl": 0, + "timeout": 0, + "round_robin": false, + "duration": 5.052973881, + "executed": 1620313661, + "history": [ + { + "status": 0, + "executed": 1620313601 + }, + { + "status": 0, + "executed": 1620313661 + } + ], + "issued": 1620313661, + "output": "CheckCPU TOTAL OK: total=0.2 user=0.2 nice=0.0 system=0.0 idle=99.8 iowait=0.0 irq=0.0 softirq=0.0 steal=0.0 guest=0.0 guest_nice=0.0\n", + "state": "passing", + "status": 0, + "total_state_change": 0, + "last_ok": 1620313661, + "occurrences": 2, + "occurrences_watermark": 2, + "output_metric_format": "", + "output_metric_handlers": null, + "env_vars": null, + "metadata": { + "name": "check_cpu", + "namespace": "default" + }, + "secrets": null, + "is_silenced": false, + "processed_by": "server1", + "scheduler": "memory" + }, + "entity": { + "entity_class": "agent", + "system": { + "hostname": "server1", + "os": "linux", + "platform": "centos", + "platform_family": "rhel", + "platform_version": "7.5.1804", + "network": { + "interfaces": [ + { + "name": "lo", + "addresses": [ + "127.0.0.1/8", + "::1/128" + ] + }, + { + "name": "eth0", + "mac": "08:00:27:8b:c9:3f", + "addresses": [ + "10.0.2.15/24", + "fe80::bc00:e2c8:1059:3868/64" + ] + }, + { + "name": "eth1", + "mac": "08:00:27:73:87:93", + "addresses": [ + "172.28.128.57/24", + "fe80::a00:27ff:fe73:8793/64" + ] + } + ] + }, + "arch": "amd64", + "libc_type": "glibc", + "vm_system": "vbox", + "vm_role": "guest", + "cloud_provider": "", + "processes": null + }, + "subscriptions": [ + "system", + "entity:server1" + ], + "last_seen": 1620313661, + "deregister": false, + "deregistration": {}, + "user": "agent", + "redact": [ + "password", + "passwd", + "pass", + "api_key", + "api_token", + "access_key", + "secret_key", + "private_key", + "secret" + ], + "metadata": { + "name": "server1", + "namespace": "default" + }, + "sensu_agent_version": "6.2.7" + }, + "pipelines": [ + { + "api_version": "core/v2", + "type": "Pipeline", + "name": "incident_alerts" + } + ], + "id": "da53be74-be42-4862-a481-b7e3236e8e6d", + "metadata": { + "namespace": "default" + }, + "sequence": 3, + "timestamp": 1620313666 + }, + { + "check": { + "handlers": [], + "high_flap_threshold": 0, + "interval": 20, + "low_flap_threshold": 0, + "publish": false, + "runtime_assets": null, + "subscriptions": [], + "proxy_entity_name": "", + "check_hooks": null, + "stdin": false, + "subdue": null, + "ttl": 0, + "timeout": 120, + "round_robin": false, + "executed": 1620313714, + "history": [ + { + "status": 0, + "executed": 1620313314 + }, + { + "status": 0, + "executed": 1620313334 + }, + { + "status": 0, + "executed": 1620313354 + }, + { + "...": 0, + "...": 1620313374 + } + ], + "issued": 1620313714, + "output": "Keepalive last sent from server1 at 2021-05-06 15:08:34 +0000 UTC", + "state": "passing", + "status": 0, + "total_state_change": 0, + "last_ok": 1620313714, + "occurrences": 358, + "occurrences_watermark": 358, + "output_metric_format": "", + "output_metric_handlers": null, + "env_vars": null, + "metadata": { + "name": "keepalive", + "namespace": "default" + }, + "secrets": null, + "is_silenced": false, + "processed_by": "server1", + "scheduler": "etcd" + }, + "entity": { + "entity_class": "agent", + "system": { + "hostname": "server1", + "os": "linux", + "platform": "centos", + "platform_family": "rhel", + "platform_version": "7.5.1804", + "network": { + "interfaces": [ + { + "name": "lo", + "addresses": [ + "127.0.0.1/8", + "::1/128" + ] + }, + { + "name": "eth0", + "mac": "08:00:27:8b:c9:3f", + "addresses": [ + "10.0.2.15/24", + "fe80::bc00:e2c8:1059:3868/64" + ] + }, + { + "name": "eth1", + "mac": "08:00:27:73:87:93", + "addresses": [ + "172.28.128.57/24", + "fe80::a00:27ff:fe73:8793/64" + ] + } + ] + }, + "arch": "amd64", + "libc_type": "glibc", + "vm_system": "vbox", + "vm_role": "guest", + "cloud_provider": "", + "processes": null + }, + "subscriptions": [ + "system", + "entity:server1" + ], + "last_seen": 1620313714, + "deregister": false, + "deregistration": {}, + "user": "agent", + "redact": [ + "password", + "passwd", + "pass", + "api_key", + "api_token", + "access_key", + "secret_key", + "private_key", + "secret" + ], + "metadata": { + "name": "server1", + "namespace": "default" + }, + "sensu_agent_version": "6.2.7" + }, + "pipelines": [ + { + "api_version": "core/v2", + "type": "Pipeline", + "name": "incident_alerts" + } + ], + "id": "8717b1dc-47d2-4b73-a259-ee2645cadbf5", + "metadata": { + "namespace": "default" + }, + "sequence": 359, + "timestamp": 1620313714 + } +] +{{< /code >}} + +### API Specification {#eventsentity-get-specification} + +/events/:entity (GET) | +---------------------|------ +description | Returns a list of events for the specified entity. +example url | http://hostname:8080/api/core/v2/namespaces/default/events/server1 +pagination | This endpoint supports [pagination][2] using the `limit` and `continue` query parameters. +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "check": { + "command": "check-cpu-usage -w 75 -c 90", + "handlers": [], + "high_flap_threshold": 0, + "interval": 60, + "low_flap_threshold": 0, + "publish": true, + "runtime_assets": [ + "check-cpu-usage" + ], + "subscriptions": [ + "system" + ], + "proxy_entity_name": "", + "check_hooks": null, + "stdin": false, + "subdue": null, + "ttl": 0, + "timeout": 0, + "round_robin": false, + "duration": 5.052973881, + "executed": 1620313661, + "history": [ + { + "status": 0, + "executed": 1620313601 + }, + { + "status": 0, + "executed": 1620313661 + } + ], + "issued": 1620313661, + "output": "CheckCPU TOTAL OK: total=0.2 user=0.2 nice=0.0 system=0.0 idle=99.8 iowait=0.0 irq=0.0 softirq=0.0 steal=0.0 guest=0.0 guest_nice=0.0\n", + "state": "passing", + "status": 0, + "total_state_change": 0, + "last_ok": 1620313661, + "occurrences": 2, + "occurrences_watermark": 2, + "output_metric_format": "", + "output_metric_handlers": null, + "env_vars": null, + "metadata": { + "name": "check_cpu", + "namespace": "default" + }, + "secrets": null, + "is_silenced": false, + "processed_by": "server1", + "scheduler": "memory" + }, + "entity": { + "entity_class": "agent", + "system": { + "hostname": "server1", + "os": "linux", + "platform": "centos", + "platform_family": "rhel", + "platform_version": "7.5.1804", + "network": { + "interfaces": [ + { + "name": "lo", + "addresses": [ + "127.0.0.1/8", + "::1/128" + ] + }, + { + "name": "eth0", + "mac": "08:00:27:8b:c9:3f", + "addresses": [ + "10.0.2.15/24", + "fe80::bc00:e2c8:1059:3868/64" + ] + }, + { + "name": "eth1", + "mac": "08:00:27:73:87:93", + "addresses": [ + "172.28.128.57/24", + "fe80::a00:27ff:fe73:8793/64" + ] + } + ] + }, + "arch": "amd64", + "libc_type": "glibc", + "vm_system": "vbox", + "vm_role": "guest", + "cloud_provider": "", + "processes": null + }, + "subscriptions": [ + "system", + "entity:server1" + ], + "last_seen": 1620313661, + "deregister": false, + "deregistration": {}, + "user": "agent", + "redact": [ + "password", + "passwd", + "pass", + "api_key", + "api_token", + "access_key", + "secret_key", + "private_key", + "secret" + ], + "metadata": { + "name": "server1", + "namespace": "default" + }, + "sensu_agent_version": "6.2.7" + }, + "pipelines": [ + { + "api_version": "core/v2", + "type": "Pipeline", + "name": "incident_alerts" + } + ], + "id": "da53be74-be42-4862-a481-b7e3236e8e6d", + "metadata": { + "namespace": "default" + }, + "sequence": 3, + "timestamp": 1620313666 + }, + { + "check": { + "handlers": [], + "high_flap_threshold": 0, + "interval": 20, + "low_flap_threshold": 0, + "publish": false, + "runtime_assets": null, + "subscriptions": [], + "proxy_entity_name": "", + "check_hooks": null, + "stdin": false, + "subdue": null, + "ttl": 0, + "timeout": 120, + "round_robin": false, + "executed": 1620313714, + "history": [ + { + "status": 0, + "executed": 1620313314 + }, + { + "status": 0, + "executed": 1620313334 + }, + { + "status": 0, + "executed": 1620313354 + }, + { + "...": 0, + "...": 1620313374 + } + ], + "issued": 1620313714, + "output": "Keepalive last sent from server1 at 2021-05-06 15:08:34 +0000 UTC", + "state": "passing", + "status": 0, + "total_state_change": 0, + "last_ok": 1620313714, + "occurrences": 358, + "occurrences_watermark": 358, + "output_metric_format": "", + "output_metric_handlers": null, + "env_vars": null, + "metadata": { + "name": "keepalive", + "namespace": "default" + }, + "secrets": null, + "is_silenced": false, + "processed_by": "server1", + "scheduler": "etcd" + }, + "entity": { + "entity_class": "agent", + "system": { + "hostname": "server1", + "os": "linux", + "platform": "centos", + "platform_family": "rhel", + "platform_version": "7.5.1804", + "network": { + "interfaces": [ + { + "name": "lo", + "addresses": [ + "127.0.0.1/8", + "::1/128" + ] + }, + { + "name": "eth0", + "mac": "08:00:27:8b:c9:3f", + "addresses": [ + "10.0.2.15/24", + "fe80::bc00:e2c8:1059:3868/64" + ] + }, + { + "name": "eth1", + "mac": "08:00:27:73:87:93", + "addresses": [ + "172.28.128.57/24", + "fe80::a00:27ff:fe73:8793/64" + ] + } + ] + }, + "arch": "amd64", + "libc_type": "glibc", + "vm_system": "vbox", + "vm_role": "guest", + "cloud_provider": "", + "processes": null + }, + "subscriptions": [ + "system", + "entity:server1" + ], + "last_seen": 1620313714, + "deregister": false, + "deregistration": {}, + "user": "agent", + "redact": [ + "password", + "passwd", + "pass", + "api_key", + "api_token", + "access_key", + "secret_key", + "private_key", + "secret" + ], + "metadata": { + "name": "server1", + "namespace": "default" + }, + "sensu_agent_version": "6.2.7" + }, + "pipelines": [ + { + "api_version": "core/v2", + "type": "Pipeline", + "name": "incident_alerts" + } + ], + "id": "8717b1dc-47d2-4b73-a259-ee2645cadbf5", + "metadata": { + "namespace": "default" + }, + "sequence": 359, + "timestamp": 1620313714 + } +] +{{< /code >}} + +## Get event data for a specific entity and check {#eventsentitycheck-get} + +The `/events/:entity/:check` API endpoint provides HTTP GET access to [event][1] data for the specified entity and check. + +### Example {#eventsentitycheck-get-example} + +In the following example, an HTTP GET request is submitted to the `/events/:entity/:check` API endpoint to retrieve the event for the `server1` entity and the `check_cpu` check: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/events/server1/check_cpu \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request will return a successful `HTTP/1.1 200 OK` response and a JSON map that contains the Sensu events for the `server1` entity and `check_cpu` check: + +{{< code text >}} +{ + "check": { + "command": "check-cpu-usage -w 75 -c 90", + "handlers": [], + "high_flap_threshold": 0, + "interval": 60, + "low_flap_threshold": 0, + "publish": true, + "runtime_assets": [ + "check-cpu-usage" + ], + "subscriptions": [ + "system" + ], + "proxy_entity_name": "", + "check_hooks": null, + "stdin": false, + "subdue": null, + "ttl": 0, + "timeout": 0, + "round_robin": false, + "duration": 5.050929017, + "executed": 1620313539, + "history": null, + "issued": 1620313539, + "output": "CheckCPU TOTAL OK: total=2.85 user=2.65 nice=0.0 system=0.2 idle=97.15 iowait=0.0 irq=0.0 softirq=0.0 steal=0.0 guest=0.0 guest_nice=0.0\n", + "state": "passing", + "status": 0, + "total_state_change": 0, + "last_ok": 1620313539, + "occurrences": 1, + "occurrences_watermark": 1, + "output_metric_format": "", + "output_metric_handlers": null, + "env_vars": null, + "metadata": { + "name": "check_cpu", + "namespace": "default" + }, + "secrets": null, + "is_silenced": false, + "processed_by": "server1", + "scheduler": "" + }, + "entity": { + "entity_class": "agent", + "system": { + "hostname": "server1", + "os": "linux", + "platform": "centos", + "platform_family": "rhel", + "platform_version": "7.5.1804", + "network": { + "interfaces": [ + { + "name": "lo", + "addresses": [ + "127.0.0.1/8", + "::1/128" + ] + }, + { + "name": "eth0", + "mac": "08:00:27:8b:c9:3f", + "addresses": [ + "10.0.2.15/24", + "fe80::bc00:e2c8:1059:3868/64" + ] + }, + { + "name": "eth1", + "mac": "08:00:27:73:87:93", + "addresses": [ + "172.28.128.57/24", + "fe80::a00:27ff:fe73:8793/64" + ] + } + ] + }, + "arch": "amd64", + "libc_type": "glibc", + "vm_system": "vbox", + "vm_role": "guest", + "cloud_provider": "", + "processes": null + }, + "subscriptions": [ + "system", + "entity:server1" + ], + "last_seen": 1620313539, + "deregister": false, + "deregistration": {}, + "user": "agent", + "redact": [ + "password", + "passwd", + "pass", + "api_key", + "api_token", + "access_key", + "secret_key", + "private_key", + "secret" + ], + "metadata": { + "name": "server1", + "namespace": "default" + }, + "sensu_agent_version": "6.2.7" + }, + "pipelines": [ + { + "api_version": "core/v2", + "type": "Pipeline", + "name": "incident_alerts" + } + ], + "id": "9a9c7515-0a04-43f3-9351-d8da88942b1b", + "metadata": { + "namespace": "default" + }, + "sequence": 1, + "timestamp": 1620313546 +} +{{< /code >}} + +### API Specification {#eventsentitycheck-get-specification} + +/events/:entity/:check (GET) | +---------------------|------ +description | Returns an event for the specified entity and check. +example url | http://hostname:8080/api/core/v2/namespaces/default/events/server1/check_cpu +response type | Map +response codes |
    • **Success**: 200 (OK)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +{ + "check": { + "command": "check-cpu-usage -w 75 -c 90", + "handlers": [], + "high_flap_threshold": 0, + "interval": 60, + "low_flap_threshold": 0, + "publish": true, + "runtime_assets": [ + "check-cpu-usage" + ], + "subscriptions": [ + "system" + ], + "proxy_entity_name": "", + "check_hooks": null, + "stdin": false, + "subdue": null, + "ttl": 0, + "timeout": 0, + "round_robin": false, + "duration": 5.050929017, + "executed": 1620313539, + "history": null, + "issued": 1620313539, + "output": "CheckCPU TOTAL OK: total=2.85 user=2.65 nice=0.0 system=0.2 idle=97.15 iowait=0.0 irq=0.0 softirq=0.0 steal=0.0 guest=0.0 guest_nice=0.0\n", + "state": "passing", + "status": 0, + "total_state_change": 0, + "last_ok": 1620313539, + "occurrences": 1, + "occurrences_watermark": 1, + "output_metric_format": "", + "output_metric_handlers": null, + "env_vars": null, + "metadata": { + "name": "check_cpu", + "namespace": "default" + }, + "secrets": null, + "is_silenced": false, + "processed_by": "server1", + "scheduler": "" + }, + "entity": { + "entity_class": "agent", + "system": { + "hostname": "server1", + "os": "linux", + "platform": "centos", + "platform_family": "rhel", + "platform_version": "7.5.1804", + "network": { + "interfaces": [ + { + "name": "lo", + "addresses": [ + "127.0.0.1/8", + "::1/128" + ] + }, + { + "name": "eth0", + "mac": "08:00:27:8b:c9:3f", + "addresses": [ + "10.0.2.15/24", + "fe80::bc00:e2c8:1059:3868/64" + ] + }, + { + "name": "eth1", + "mac": "08:00:27:73:87:93", + "addresses": [ + "172.28.128.57/24", + "fe80::a00:27ff:fe73:8793/64" + ] + } + ] + }, + "arch": "amd64", + "libc_type": "glibc", + "vm_system": "vbox", + "vm_role": "guest", + "cloud_provider": "", + "processes": null + }, + "subscriptions": [ + "system", + "entity:server1" + ], + "last_seen": 1620313539, + "deregister": false, + "deregistration": {}, + "user": "agent", + "redact": [ + "password", + "passwd", + "pass", + "api_key", + "api_token", + "access_key", + "secret_key", + "private_key", + "secret" + ], + "metadata": { + "name": "server1", + "namespace": "default" + }, + "sensu_agent_version": "6.2.7" + }, + "pipelines": [ + { + "api_version": "core/v2", + "type": "Pipeline", + "name": "incident_alerts" + } + ], + "id": "9a9c7515-0a04-43f3-9351-d8da88942b1b", + "metadata": { + "namespace": "default" + }, + "sequence": 1, + "timestamp": 1620313546 +} +{{< /code >}} + +## Create a new event for an entity and check {#eventsentitycheck-post} + +The `/events/:entity/:check` API endpoint provides HTTP POST access to create an event and send it to the Sensu observability pipeline. + +### Example {#eventsentitycheck-post-example} + +In the following example, an HTTP POST request is submitted to the `/events/:entity/:check` API endpoint to create an event for the `server1` entity and the `server-health` check and process it using the `incident_alerts` pipeline. +The event includes a status code of `1`, indicating a warning, and an output message of `Server error`. + +{{< code shell >}} +curl -X POST \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "entity": { + "entity_class": "proxy", + "metadata": { + "name": "server1", + "namespace": "default" + } + }, + "check": { + "output": "Server error", + "status": 1, + "interval": 60, + "metadata": { + "name": "server-health" + } + }, + "pipelines": [ + { + "api_version": "core/v2", + "type": "Pipeline", + "name": "incident_alerts" + } + ] +} \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/events/server1/server-health +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +{{% notice note %}} +**NOTE**: A namespace is not required to create the event. +The event will use the namespace in the URL by default. +{{% /notice %}} + +You can use sensuctl or the [Sensu web UI][4] to view the event: + +{{< code shell >}} +sensuctl event list +{{< /code >}} + +The response should list the event with the status and output specified in the request: + +{{< code text >}} + Entity Check Output Status Silenced Timestamp +────────────── ───────────── ─────────────────────────────────── ──────── ────────── ─────────────────────────────── + server1 server-health Server error 1 false 2019-03-14 16:56:09 +0000 UTC +{{< /code >}} + +For events created with this endpoint, the following attributes have the default value `0` unless you specify a different value for testing: + +- `executed` +- `issued` +- `last_seen` +- `status` + +The `last_ok` attribute will default to `0` even if you manually specify OK status in the request body. + +The `sensu_agent_version` attribute will return with a null value for events created with this endpoint because these events are not created by an agent-executed check. + +### API Specification {#eventsentitycheck-post-specification} + +/events/:entity/:check (POST) | +----------------|------ +description | Creates an event for the specified entity and check. +example url | http://hostname:8080/api/core/v2/namespaces/default/events/server1/server-health +payload | {{< code shell >}} +{ + "entity": { + "entity_class": "proxy", + "metadata": { + "name": "server1", + "namespace": "default" + } + }, + "check": { + "output": "Server error", + "status": 1, + "interval": 60, + "metadata": { + "name": "server-health" + } + }, + "pipelines": [ + { + "api_version": "core/v2", + "type": "Pipeline", + "name": "incident_alerts" + } + ] +} +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + +## Create or update an event for an entity and check {#eventsentitycheck-put} + +The `/events/:entity/:check` API endpoint provides HTTP PUT access to create or update an event and send it to the Sensu observability pipeline. + +### Example {#eventsentitycheck-put-example} + +In the following example, an HTTP PUT request is submitted to the `/events/:entity/:check` API endpoint to create an event for the `server1` entity and the `server-health` check and process it using the `incident_alerts` pipeline. +The event includes a status code of `1`, indicating a warning, and an output message of `Server error`. + +{{< code shell >}} +curl -X PUT \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "entity": { + "entity_class": "proxy", + "metadata": { + "name": "server1", + "namespace": "default" + } + }, + "check": { + "output": "Server error", + "status": 1, + "interval": 60, + "metadata": { + "name": "server-health" + } + }, + "pipelines": [ + { + "api_version": "core/v2", + "type": "Pipeline", + "name": "incident_alerts" + } + ] +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/events/server1/server-health +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +{{% notice note %}} +**NOTE**: A namespace is not required to create the event. +The event will use the namespace in the URL by default. +{{% /notice %}} + +You can use sensuctl or the [Sensu web UI][4] to view the event: + +{{< code shell >}} +sensuctl event list +{{< /code >}} + +The response should list the event with the status and output specified in the request: + +{{< code text >}} + Entity Check Output Status Silenced Timestamp +────────────── ───────────── ─────────────────────────────────── ──────── ────────── ─────────────────────────────── + server1 server-health Server error 1 false 2019-03-14 16:56:09 +0000 UTC +{{< /code >}} + +### API Specification {#eventsentitycheck-put-specification} + +/events/:entity/:check (PUT) | +----------------|------ +description | Creates an event for the specified entity and check. +example url | http://hostname:8080/api/core/v2/namespaces/default/events/server1/server-health +payload | {{< code shell >}} +{ + "entity": { + "entity_class": "proxy", + "metadata": { + "name": "server1", + "namespace": "default" + } + }, + "check": { + "output": "Server error", + "status": 1, + "interval": 60, + "metadata": { + "name": "server-health" + } + }, + "pipelines": [ + { + "api_version": "core/v2", + "type": "Pipeline", + "name": "incident_alerts" + } + ] +} +{{< /code >}} +payload parameters | Review the [payload parameters][5] section below. +response codes |
    • **Success**: 201 (Created)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + +#### Payload parameters {#eventsentitycheck-put-parameters} + +The `/events/:entity/:check` PUT endpoint requires a request payload that contains an `entity` scope and a `check` scope. + +- The `entity` scope contains information about the component of your infrastructure represented by the event. +At minimum, Sensu requires the `entity` scope to contain the `entity_class` (`agent` or `proxy`) and the entity `name` and `namespace` within a `metadata` scope. +For more information about entity attributes, review the [entity specification][6]. +- The `check` scope contains information about the event status and how the event was created. +At minimum, Sensu requires the `check` scope to contain a `name` within a `metadata` scope and either an `interval` or `cron` attribute. +For more information about check attributes, review the [check specification][7]. + +**Example request with minimum required event attributes** + +{{< code shell >}} +curl -X PUT \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "entity": { + "entity_class": "proxy", + "metadata": { + "name": "server1" + } + }, + "check": { + "interval": 60, + "metadata": { + "name": "server-health" + } + } +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/events/server1/server-health +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +The minimum required attributes let you create an event using the `/events/:entity/:check` PUT endpoint, but the request can include any attributes defined in the [event specification][8]. +To create useful, actionable events, we recommend adding check attributes such as the event `status` (`0` for OK, `1` for warning, `2` for critical), an `output` message, and one or more `pipelines`. +For more information about these attributes and their available values, review the [event specification][8]. + +**Example request with minimum recommended event attributes** + +{{< code shell >}} +curl -X PUT \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "entity": { + "entity_class": "proxy", + "metadata": { + "name": "server1", + "namespace": "default" + } + }, + "check": { + "output": "Server error", + "status": 1, + "interval": 60, + "metadata": { + "name": "server-health" + } + }, + "pipelines": [ + { + "api_version": "core/v2", + "type": "Pipeline", + "name": "incident_alerts" + } + ] +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/events/server1/server-health +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +#### Create metrics events + +In addition to the `entity` and `check` scopes, Sensu events can include a `metrics` scope that contains metrics in Sensu metric format. +Read the [events reference][9] and for more information about Sensu metric format. + +**Example request including metrics** + +{{< code shell >}} +curl -X PUT \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "entity": { + "entity_class": "proxy", + "metadata": { + "name": "server1", + "namespace": "default" + } + }, + "check": { + "status": 0, + "output_metric_handlers": ["influxdb"], + "interval": 60, + "metadata": { + "name": "server-metrics" + } + }, + "metrics": { + "handlers": [ + "influxdb" + ], + "points": [ + { + "name": "server1.server-metrics.time_total", + "tags": [], + "timestamp": 1552506033, + "value": 0.005 + }, + { + "name": "server1.server-metrics.time_namelookup", + "tags": [], + "timestamp": 1552506033, + "value": 0.004 + } + ] + }, + "pipelines": [ + { + "api_version": "core/v2", + "type": "Pipeline", + "name": "metrics_workflows" + } + ] +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/events/server1/server-metrics +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +## Delete an event {#eventsentitycheck-delete} + +### Example {#eventsentitycheck-delete-example} + +The following example shows a request to the `/events/:entity/:check` API endpoint to delete the event produced by the `server1` entity and `check_cpu` check, resulting in a successful `HTTP/1.1 204 No Content` response. + +{{< code shell >}} +curl -X DELETE \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/events/server1/check_cpu \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +### API Specification {#eventsentitycheck-delete-specification} + +/events/:entity/:check (DELETE) | +--------------------------|------ +description | Deletes the event created by the specified entity using the specified check. +example url | http://hostname:8080/api/core/v2/namespaces/default/events/server1/check_cpu +response codes |
    • **Success**: 204 (No Content)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + +## Get a subset of events with response filtering + +The `/events` API endpoint supports [response filtering][10] for a subset of event data based on labels and the following fields: + +- `event.name` +- `event.namespace` +- `event.is_silenced` +- `event.check.handlers` +- `event.check.is_silenced` +- `event.check.name` +- `event.check.publish` +- `event.check.round_robin` +- `event.check.runtime_assets` +- `event.check.status` +- `event.check.subscriptions` +- `event.entity.deregister` +- `event.entity.entity_class` +- `event.entity.name` +- `event.entity.subscriptions` + +### Example + +The following example demonstrates a request to the `/events` API endpoint with [response filtering][10] for events from entities whose subscriptions include `linux`: + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/events -G \ +--data-urlencode 'fieldSelector="linux" in event.entity.subscriptions' +{{< /code >}} + +The example request will result in a successful `HTTP/1.1 200 OK` response and a JSON array that contains only [event definitions][1] for entities whose subscriptions include `linux`: + +{{< code text >}} +[ + { + "timestamp": 1644848031, + "entity": { + "entity_class": "agent", + "system": { + "hostname": "sensu-centos", + "os": "linux", + "platform": "centos", + "platform_family": "rhel", + "platform_version": "7.5.1804", + "network": { + "interfaces": [ + { + "name": "lo", + "addresses": [ + "127.0.0.1/8", + "::1/128" + ] + }, + { + "name": "eth0", + "mac": "08:00:27:8b:c9:3f", + "addresses": [ + "10.0.2.15/24", + "fe80::c68e:8fd8:32f0:7c5d/64" + ] + }, + { + "name": "eth1", + "mac": "08:00:27:3b:a9:9f", + "addresses": [ + "192.168.56.23/24", + "fe80::a00:27ff:fe3b:a99f/64" + ] + } + ] + }, + "arch": "amd64", + "libc_type": "glibc", + "vm_system": "vbox", + "vm_role": "guest", + "cloud_provider": "", + "processes": null + }, + "subscriptions": [ + "linux", + "entity:sensu-centos", + "system" + ], + "last_seen": 1644848029, + "deregister": false, + "deregistration": {}, + "user": "agent", + "redact": [ + "password", + "passwd", + "pass", + "api_key", + "api_token", + "access_key", + "secret_key", + "private_key", + "secret" + ], + "metadata": { + "name": "sensu-centos", + "namespace": "default", + "created_by": "admin" + }, + "sensu_agent_version": "6.6.5" + }, + "check": { + "command": "check-cpu-usage -w 1 -c 2", + "handlers": [], + "high_flap_threshold": 0, + "interval": 15, + "low_flap_threshold": 0, + "publish": true, + "runtime_assets": [ + "check-cpu-usage" + ], + "subscriptions": [ + "system" + ], + "proxy_entity_name": "", + "check_hooks": null, + "stdin": false, + "subdue": null, + "ttl": 0, + "timeout": 0, + "round_robin": false, + "duration": 2.010462294, + "executed": 1644848029, + "history": [ + { + "status": 2, + "executed": 1644847740 + }, + { + "status": 1, + "executed": 1644847755 + }, + { + "status": 1, + "executed": 1644847770 + }, + { + "status": 2, + "executed": 1644847785 + }, + { + "status": 2, + "executed": 1644847800 + }, + { + "status": 1, + "executed": 1644847815 + }, + { + "status": 2, + "executed": 1644847830 + }, + { + "status": 1, + "executed": 1644847845 + }, + { + "status": 1, + "executed": 1644847860 + }, + { + "status": 1, + "executed": 1644847875 + }, + { + "status": 1, + "executed": 1644847890 + }, + { + "status": 0, + "executed": 1644847905 + }, + { + "status": 2, + "executed": 1644847920 + }, + { + "status": 1, + "executed": 1644847935 + }, + { + "status": 0, + "executed": 1644847950 + }, + { + "status": 0, + "executed": 1644847965 + }, + { + "status": 2, + "executed": 1644847980 + }, + { + "status": 2, + "executed": 1644847995 + }, + { + "status": 1, + "executed": 1644848010 + }, + { + "status": 1, + "executed": 1644848014 + }, + { + "status": 0, + "executed": 1644848029 + } + ], + "issued": 1644848029, + "output": "check-cpu-usage OK: 0.51% CPU usage | cpu_idle=99.49, cpu_system=0.51, cpu_user=0.00, cpu_nice=0.00, cpu_iowait=0.00, cpu_irq=0.00, cpu_softirq=0.00, cpu_steal=0.00, cpu_guest=0.00, cpu_guestnice=0.00\n", + "state": "passing", + "status": 0, + "total_state_change": 59, + "last_ok": 1644848029, + "occurrences": 1, + "occurrences_watermark": 2, + "output_metric_format": "", + "output_metric_handlers": null, + "env_vars": null, + "metadata": { + "name": "check_cpu", + "namespace": "default" + }, + "secrets": null, + "is_silenced": false, + "scheduler": "memory", + "processed_by": "sensu-centos", + "pipelines": [] + }, + "metadata": { + "namespace": "default" + }, + "id": "f5ef6190-a8e2-4660-9ad1-02ae0a2e89f4", + "sequence": 2, + "pipelines": [ + { + "api_version": "core/v2", + "type": "Pipeline", + "name": "metrics_workflows" + } + ] + } +] +{{< /code >}} + +{{% notice note %}} +**NOTE**: Read [API response filtering](../../#response-filtering) for more filter statement examples that demonstrate how to filter responses using different operators with label and field selectors. +{{% /notice %}} + +### API Specification + +/events (GET) with response filters | +---------------|------ +description | Returns the list of events that match the [response filters][10] applied in the API request. +example url | http://hostname:8080/api/core/v2/events +pagination | This endpoint supports [pagination][2] using the `limit` and `continue` query parameters. +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "timestamp": 1644848031, + "entity": { + "entity_class": "agent", + "system": { + "hostname": "sensu-centos", + "os": "linux", + "platform": "centos", + "platform_family": "rhel", + "platform_version": "7.5.1804", + "network": { + "interfaces": [ + { + "name": "lo", + "addresses": [ + "127.0.0.1/8", + "::1/128" + ] + }, + { + "name": "eth0", + "mac": "08:00:27:8b:c9:3f", + "addresses": [ + "10.0.2.15/24", + "fe80::c68e:8fd8:32f0:7c5d/64" + ] + }, + { + "name": "eth1", + "mac": "08:00:27:3b:a9:9f", + "addresses": [ + "192.168.56.23/24", + "fe80::a00:27ff:fe3b:a99f/64" + ] + } + ] + }, + "arch": "amd64", + "libc_type": "glibc", + "vm_system": "vbox", + "vm_role": "guest", + "cloud_provider": "", + "processes": null + }, + "subscriptions": [ + "linux", + "entity:sensu-centos", + "system" + ], + "last_seen": 1644848029, + "deregister": false, + "deregistration": {}, + "user": "agent", + "redact": [ + "password", + "passwd", + "pass", + "api_key", + "api_token", + "access_key", + "secret_key", + "private_key", + "secret" + ], + "metadata": { + "name": "sensu-centos", + "namespace": "default", + "created_by": "admin" + }, + "sensu_agent_version": "6.6.5" + }, + "check": { + "command": "check-cpu-usage -w 1 -c 2", + "handlers": [], + "high_flap_threshold": 0, + "interval": 15, + "low_flap_threshold": 0, + "publish": true, + "runtime_assets": [ + "check-cpu-usage" + ], + "subscriptions": [ + "system" + ], + "proxy_entity_name": "", + "check_hooks": null, + "stdin": false, + "subdue": null, + "ttl": 0, + "timeout": 0, + "round_robin": false, + "duration": 2.010462294, + "executed": 1644848029, + "history": [ + { + "status": 2, + "executed": 1644847740 + }, + { + "status": 1, + "executed": 1644847755 + }, + { + "status": 1, + "executed": 1644847770 + }, + { + "status": 2, + "executed": 1644847785 + }, + { + "status": 2, + "executed": 1644847800 + }, + { + "status": 1, + "executed": 1644847815 + }, + { + "status": 2, + "executed": 1644847830 + }, + { + "status": 1, + "executed": 1644847845 + }, + { + "status": 1, + "executed": 1644847860 + }, + { + "status": 1, + "executed": 1644847875 + }, + { + "status": 1, + "executed": 1644847890 + }, + { + "status": 0, + "executed": 1644847905 + }, + { + "status": 2, + "executed": 1644847920 + }, + { + "status": 1, + "executed": 1644847935 + }, + { + "status": 0, + "executed": 1644847950 + }, + { + "status": 0, + "executed": 1644847965 + }, + { + "status": 2, + "executed": 1644847980 + }, + { + "status": 2, + "executed": 1644847995 + }, + { + "status": 1, + "executed": 1644848010 + }, + { + "status": 1, + "executed": 1644848014 + }, + { + "status": 0, + "executed": 1644848029 + } + ], + "issued": 1644848029, + "output": "check-cpu-usage OK: 0.51% CPU usage | cpu_idle=99.49, cpu_system=0.51, cpu_user=0.00, cpu_nice=0.00, cpu_iowait=0.00, cpu_irq=0.00, cpu_softirq=0.00, cpu_steal=0.00, cpu_guest=0.00, cpu_guestnice=0.00\n", + "state": "passing", + "status": 0, + "total_state_change": 59, + "last_ok": 1644848029, + "occurrences": 1, + "occurrences_watermark": 2, + "output_metric_format": "", + "output_metric_handlers": null, + "env_vars": null, + "metadata": { + "name": "check_cpu", + "namespace": "default" + }, + "secrets": null, + "is_silenced": false, + "scheduler": "memory", + "processed_by": "sensu-centos", + "pipelines": [] + }, + "metadata": { + "namespace": "default" + }, + "id": "f5ef6190-a8e2-4660-9ad1-02ae0a2e89f4", + "sequence": 2, + "pipelines": [ + { + "api_version": "core/v2", + "type": "Pipeline", + "name": "metrics_workflows" + } + ] + } +] +{{< /code >}} + + +[1]: ../../../observability-pipeline/observe-events/events/ +[2]: ../../#pagination +[3]: #eventsentitycheck-put +[4]: ../../../web-ui/ +[5]: #eventsentitycheck-put-parameters +[6]: ../../../observability-pipeline/observe-entities/entities#entities-specification +[7]: ../../../observability-pipeline/observe-schedule/checks#check-specification +[8]: ../../../observability-pipeline/observe-events/events/#event-specification +[9]: ../../../observability-pipeline/observe-events/events#metrics-attribute +[10]: ../../#response-filtering +[11]: #eventsentitycheck-put diff --git a/content/sensu-go/6.12/api/core/filters.md b/content/sensu-go/6.12/api/core/filters.md new file mode 100644 index 0000000000..5d9028eab0 --- /dev/null +++ b/content/sensu-go/6.12/api/core/filters.md @@ -0,0 +1,422 @@ +--- +title: "core/v2/filters" +description: "Read this API documentation for information about Sensu core/v2/filters API endpoints, with examples for retrieving and managing event filters." +core_api_title: "core/v2/filters" +type: "core_api" +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: core +--- + +{{% notice note %}} +**NOTE**: Requests to `core/v2/filters` API endpoints require you to authenticate with a Sensu [API key](../../#configure-an-environment-variable-for-api-key-authentication) or [access token](../../#authenticate-with-auth-api-endpoints). +The code examples in this document use the [environment variable](../../#configure-an-environment-variable-for-api-key-authentication) `$SENSU_API_KEY` to represent a valid API key in API requests. +{{% /notice %}} + +## Get all event filters + +The `/filters` API endpoint provides HTTP GET access to [event filter][1] data. + +### Example {#filters-get-example} + +The following example demonstrates a GET request to the `/filters` API endpoint: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/filters \ +-H "Authorization: Bearer $TOKEN" +{{< /code >}} + +The request results in a successful `HTTP/1.1 200 OK` response and a JSON array that contains the [event filter definitions][1] in the `default` namespace: + +{{< code text >}} +[ + { + "metadata": { + "name": "development_filter", + "namespace": "default", + "created_by": "admin" + }, + "action": "deny", + "expressions": [ + "event.entity.metadata.namespace == 'development'" + ], + "runtime_assets": null + }, + { + "metadata": { + "name": "state_change_only", + "namespace": "default" + }, + "action": "allow", + "expressions": [ + "event.check.occurrences == 1" + ], + "runtime_assets": null + } +] +{{< /code >}} + +### API Specification {#filters-get-specification} + +/filters (GET) | +---------------|------ +description | Returns the list of event filters. +example url | http://hostname:8080/api/core/v2/namespaces/default/filters +pagination | This endpoint supports [pagination][2] using the `limit` and `continue` query parameters. +response filtering | This endpoint supports [API response filtering][3]. +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "metadata": { + "name": "development_filter", + "namespace": "default", + "created_by": "admin" + }, + "action": "deny", + "expressions": [ + "event.entity.metadata.namespace == 'development'" + ], + "runtime_assets": null + }, + { + "metadata": { + "name": "state_change_only", + "namespace": "default" + }, + "action": "allow", + "expressions": [ + "event.check.occurrences == 1" + ], + "runtime_assets": null + } +] +{{< /code >}} + +## Create a new event filter + +The `/filters` API endpoint provides HTTP POST access to create an event filter. + +### Example {#filters-post-example} + +In the following example, an HTTP POST request is submitted to the `/filters` API endpoint to create the event filter `development_filter`. + +{{< code shell >}} +curl -X POST \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "metadata": { + "name": "development_filter", + "namespace": "default", + "labels": null, + "annotations": null + }, + "action": "deny", + "expressions": [ + "event.entity.metadata.namespace == 'development'" + ], + "runtime_assets": [] +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/filters +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#filters-post-specification} + +/filters (POST) | +----------------|------ +description | Creates a Sensu event filter. +example URL | http://hostname:8080/api/core/v2/namespaces/default/filters +payload | {{< code shell >}} +{ + "metadata": { + "name": "development_filter", + "namespace": "default", + "labels": null, + "annotations": null + }, + "action": "deny", + "expressions": [ + "event.entity.metadata.namespace == 'development'" + ], + "runtime_assets": [] +} +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Get a specific event filter {#filtersfilter-get} + +The `/filters/:filter` API endpoint provides HTTP GET access to [event filter data][1] for specific `:filter` definitions, by filter name. + +### Example {#filtersfilter-get-example} + +The following example queries the `/filters/:filter` API endpoint for the `:filter` named `state_change_only`: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/filters/state_change_only \ +-H "Authorization: Bearer $TOKEN" +{{< /code >}} + +The request will return a successful `HTTP/1.1 200 OK` response and a JSON map that contains the requested [`:filter` definition][1] (in this example, `state_change_only`): + +{{< code text >}} +{ + "metadata": { + "name": "state_change_only", + "namespace": "default", + "created_by": "admin" + }, + "action": "allow", + "expressions": [ + "event.check.occurrences == 1" + ], + "runtime_assets": null +} +{{< /code >}} + +### API Specification {#filtersfilter-get-specification} + +/filters/:filter (GET) | +---------------------|------ +description | Returns the specified event filter. +example url | http://hostname:8080/api/core/v2/namespaces/default/filters/state_change_only +response type | Map +response codes |
    • **Success**: 200 (OK)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +{ + "metadata": { + "name": "state_change_only", + "namespace": "default", + "created_by": "admin" + }, + "action": "allow", + "expressions": [ + "event.check.occurrences == 1" + ], + "runtime_assets": null +} +{{< /code >}} + +## Create or update an event filter {#filtersfilter-put} + +The `/filters/:filter` API endpoint provides HTTP PUT access to create or update an event filter. + +### Example {#filters-put-example} + +In the following example, an HTTP PUT request is submitted to the `/filters` API endpoint to create the event filter `development_filter`: + +{{< code shell >}} +curl -X PUT \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "metadata": { + "name": "development_filter", + "namespace": "default", + "labels": null, + "annotations": null + }, + "action": "deny", + "expressions": [ + "event.entity.metadata.namespace == 'development'" + ], + "runtime_assets": [] +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/filters/development_filter +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#filtersfilter-put-specification} + +/filters/:filter (PUT) | +----------------|------ +description | Creates or updates the specified Sensu event filter. +example URL | http://hostname:8080/api/core/v2/namespaces/default/filters/development_filter +payload | {{< code shell >}} +{ + "metadata": { + "name": "development_filter", + "namespace": "default", + "labels": null, + "annotations": null + }, + "action": "deny", + "expressions": [ + "event.entity.metadata.namespace == 'development'" + ], + "runtime_assets": [] +} +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Update a filter with PATCH + +The `/filters/:filter` API endpoint provides HTTP PATCH access to update `:filter` definitions, specified by filter name. + +{{% notice note %}} +**NOTE**: You cannot change a resource's `name` or `namespace` with a PATCH request. +Use a [PUT request](#filtersfilter-put) instead.

    +Also, you cannot add elements to an array with a PATCH request — you must replace the entire array. +{{% /notice %}} + +### Example + +In the following example, an HTTP PATCH request is submitted to the `/filters/:filter` API endpoint to update the expressions array for the `us-west` filter, resulting in a `HTTP/1.1 200 OK` response and the updated event filter definition. + +We support [JSON merge patches][4], so you must set the `Content-Type` header to `application/merge-patch+json` for PATCH requests. + +{{< code shell >}} +curl -X PATCH \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/merge-patch+json' \ +-d '{ + "expressions": [ + "event.check.occurrences == 3" + ] +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/filter/us-west +{{< /code >}} + +### API Specification + +/filters/:filter (PATCH) | +----------------|------ +description | Updates the specified Sensu filter. +example URL | http://hostname:8080/api/core/v2/namespaces/default/filter/us-west +payload | {{< code shell >}} +{ + "expressions": [ + "event.check.occurrences == 3" + ] +} +{{< /code >}} +response codes |
    • **Success**: 200 (OK)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Delete an event filter {#filtersfilter-delete} + +The `/filters/:filter` API endpoint provides HTTP DELETE access to delete an event filter from Sensu (specified by the filter name). + +### Example {#filtersfilter-delete-example} + +The following example shows a request to the `/filters/:filter` API endpoint to delete the event filter `development_filter`, which will result in a successful `HTTP/1.1 204 No Content` response: + +{{< code shell >}} +curl -X DELETE \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/filters/development_filter \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +### API Specification {#filtersfilter-delete-specification} + +/filters/:filter (DELETE) | +--------------------------|------ +description | Removes the specified event filter from Sensu. +example url | http://hostname:8080/api/core/v2/namespaces/default/filters/development_filter +response codes |
    • **Success**: 204 (No Content)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + +## Get a subset of filters with response filtering + +The `/filters` API endpoint supports [response filtering][3] for a subset of filter data based on labels and the following fields: + +- `filter.name` +- `filter.namespace` +- `filter.action` +- `filter.runtime_assets` + +### Example + +The following example demonstrates a request to the `/filters` API endpoint with [response filtering][3] for only [filter definitions][1] whose action is `allow`: + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/filters -G \ +--data-urlencode 'fieldSelector=filter.action == allow' +{{< /code >}} + +The example request will result in a successful `HTTP/1.1 200 OK` response and a JSON array that contains only [event filter definitions][1] whose action is `allow`: + +{{< code text >}} +[ + { + "metadata": { + "name": "filter_interval_60_hourly", + "namespace": "default", + "created_by": "admin" + }, + "action": "allow", + "expressions": [ + "event.check.interval == 60", + "event.check.occurrences == 1 || event.check.occurrences % 60 == 0" + ], + "runtime_assets": null + }, + { + "metadata": { + "name": "state_change_only", + "namespace": "default", + "created_by": "admin" + }, + "action": "allow", + "expressions": [ + "event.check.occurrences == 1" + ], + "runtime_assets": null + } +] +{{< /code >}} + +{{% notice note %}} +**NOTE**: Read [API response filtering](../../#response-filtering) for more filter statement examples that demonstrate how to filter responses using different operators with label and field selectors. +{{% /notice %}} + +### API Specification + +/filters (GET) with response filters | +---------------|------ +description | Returns the list of filters that match the [response filters][3] applied in the API request. +example url | http://hostname:8080/api/core/v2/filters +pagination | This endpoint supports [pagination][2] using the `limit` and `continue` query parameters. +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "metadata": { + "name": "filter_interval_60_hourly", + "namespace": "default", + "created_by": "admin" + }, + "action": "allow", + "expressions": [ + "event.check.interval == 60", + "event.check.occurrences == 1 || event.check.occurrences % 60 == 0" + ], + "runtime_assets": null + }, + { + "metadata": { + "name": "state_change_only", + "namespace": "default", + "created_by": "admin" + }, + "action": "allow", + "expressions": [ + "event.check.occurrences == 1" + ], + "runtime_assets": null + } +] +{{< /code >}} + + +[1]: ../../../observability-pipeline/observe-filter/filters/ +[2]: ../../#pagination +[3]: ../../#response-filtering +[4]: https://tools.ietf.org/html/rfc7396 diff --git a/content/sensu-go/6.12/api/core/handlers.md b/content/sensu-go/6.12/api/core/handlers.md new file mode 100644 index 0000000000..17de843ce9 --- /dev/null +++ b/content/sensu-go/6.12/api/core/handlers.md @@ -0,0 +1,493 @@ +--- +title: "core/v2/handlers" +description: "Read this API documentation for information about Sensu core/v2/handlers API endpoints, with examples for retrieving and managing handlers." +core_api_title: "core/v2/handlers" +type: "core_api" +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: core +--- + +{{% notice note %}} +**NOTE**: Requests to `core/v2/handlers` API endpoints require you to authenticate with a Sensu [API key](../../#configure-an-environment-variable-for-api-key-authentication) or [access token](../../#authenticate-with-auth-api-endpoints). +The code examples in this document use the [environment variable](../../#configure-an-environment-variable-for-api-key-authentication) `$SENSU_API_KEY` to represent a valid API key in API requests. +{{% /notice %}} + +## Get all handlers + +The `/handlers` API endpoint provides HTTP GET access to [handler][1] data. + +### Example {#handlers-get-example} + +The following example demonstrates a GET request to the `/handlers` API endpoint: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/handlers \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request results in a successful `HTTP/1.1 200 OK` response and a JSON array that contains the [handler definitions][1] in the `default` namespace: + +{{< code text >}} +[ + { + "metadata": { + "name": "influx-db", + "namespace": "default", + "created_by": "admin" + }, + "type": "pipe", + "command": "sensu-influxdb-handler -d sensu", + "timeout": 0, + "handlers": null, + "filters": null, + "env_vars": [ + "INFLUXDB_ADDR=http://influxdb.default.svc.cluster.local:8086", + "INFLUXDB_USER=sensu", + "INFLUXDB_PASSWORD=password" + ], + "runtime_assets": ["sensu/sensu-influxdb-handler"] + }, + { + "metadata": { + "name": "slack", + "namespace": "default", + "created_by": "admin" + }, + "type": "pipe", + "command": "sensu-slack-handler --channel '#monitoring'", + "timeout": 0, + "handlers": null, + "filters": [ + "is_incident", + "not_silenced" + ], + "env_vars": [ + "SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX" + ], + "runtime_assets": ["sensu/sensu-influxdb-handler"] + } +] +{{< /code >}} + +### API Specification {#handlers-get-specification} + +/handlers (GET) | +---------------|------ +description | Returns the list of handlers. +example url | http://hostname:8080/api/core/v2/namespaces/default/handlers +pagination | This endpoint supports [pagination][2] using the `limit` and `continue` query parameters. +response filtering | This endpoint supports [API response filtering][3]. +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "metadata": { + "name": "influx-db", + "namespace": "default", + "created_by": "admin" + }, + "type": "pipe", + "command": "sensu-influxdb-handler -d sensu", + "timeout": 0, + "handlers": null, + "filters": null, + "env_vars": [ + "INFLUXDB_ADDR=http://influxdb.default.svc.cluster.local:8086", + "INFLUXDB_USER=sensu", + "INFLUXDB_PASSWORD=password" + ], + "runtime_assets": ["sensu/sensu-influxdb-handler"] + }, + { + "metadata": { + "name": "slack", + "namespace": "default" + }, + "type": "pipe", + "command": "sensu-slack-handler --channel '#monitoring'", + "timeout": 0, + "handlers": null, + "filters": [ + "is_incident", + "not_silenced" + ], + "env_vars": [ + "SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX" + ], + "runtime_assets": ["sensu/sensu-slack-handler"] + } +] +{{< /code >}} + +## Create a new handler + +The `/handlers` API endpoint provides HTTP POST access to create a handler. + +### Example {#handlers-post-example} + +In the following example, an HTTP POST request is submitted to the `/handlers` API endpoint to create the event handler `influx-db`: + +{{< code shell >}} +curl -X POST \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "metadata": { + "name": "influx-db", + "namespace": "default", + "labels": null, + "annotations": null + }, + "command": "sensu-influxdb-handler -d sensu", + "env_vars": [ + "INFLUXDB_ADDR=http://influxdb.default.svc.cluster.local:8086", + "INFLUXDB_USER=sensu", + "INFLUXDB_PASSWORD=password" + ], + "filters": [], + "handlers": [], + "runtime_assets": [], + "timeout": 0, + "type": "pipe" +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/handlers +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#handlers-post-specification} + +/handlers (POST) | +----------------|------ +description | Creates a Sensu handler. +example URL | http://hostname:8080/api/core/v2/namespaces/default/handlers +payload | {{< code shell >}} +{ + "metadata": { + "name": "influx-db", + "namespace": "default", + "labels": null, + "annotations": null + }, + "command": "sensu-influxdb-handler -d sensu", + "env_vars": [ + "INFLUXDB_ADDR=http://influxdb.default.svc.cluster.local:8086", + "INFLUXDB_USER=sensu", + "INFLUXDB_PASSWORD=password" + ], + "filters": [], + "handlers": [], + "runtime_assets": [], + "timeout": 0, + "type": "pipe" +} +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Get a specific handler {#handlershandler-get} + +The `/handlers/:handler` API endpoint provides HTTP GET access to [handler data][1] for specific `:handler` definitions, by handler name. + +### Example {#handlershandler-get-example} + +The following example queries the `/handlers/:handler` API endpoint for the `:handler` named `slack`: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/handlers/slack \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request will return a successful `HTTP/1.1 200 OK` response and a JSON map that contains the requested [`:handler` definition][1] (in this example, `slack`): + +{{< code text >}} +{ + "metadata": { + "name": "slack", + "namespace": "default", + "created_by": "admin", + "labels": null, + "annotations": null + }, + "command": "sensu-slack-handler --channel '#monitoring'", + "env_vars": [ + "SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX" + ], + "filters": [ + "is_incident", + "not_silenced" + ], + "handlers": [], + "runtime_assets": [], + "timeout": 0, + "type": "pipe" +} +{{< /code >}} + +### API Specification {#handlershandler-get-specification} + +/handlers/:handler (GET) | +---------------------|------ +description | Returns a handler. +example url | http://hostname:8080/api/core/v2/namespaces/default/handlers/slack +response type | Map +response codes |
    • **Success**: 200 (OK)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +{ + "metadata": { + "name": "slack", + "namespace": "default", + "created_by": "admin", + "labels": null, + "annotations": null + }, + "command": "sensu-slack-handler --channel '#monitoring'", + "env_vars": [ + "SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX" + ], + "filters": [ + "is_incident", + "not_silenced" + ], + "handlers": [], + "runtime_assets": [], + "timeout": 0, + "type": "pipe" +} +{{< /code >}} + +## Create or update a handler {#handlershandler-put} + +The `/handlers/:handler` API endpoint provides HTTP PUT access to create or update a specific `:handler` definition, by handler name. + +### Example {#handlershandler-put-example} + +In the following example, an HTTP PUT request is submitted to the `/handlers/:handler` API endpoint to create the handler `influx-db`: + +{{< code shell >}} +curl -X PUT \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "metadata": { + "name": "influx-db", + "namespace": "default", + "labels": null, + "annotations": null + }, + "command": "sensu-influxdb-handler -d sensu", + "env_vars": [ + "INFLUXDB_ADDR=http://influxdb.default.svc.cluster.local:8086", + "INFLUXDB_USER=sensu", + "INFLUXDB_PASSWORD=password" + ], + "filters": [], + "handlers": [], + "runtime_assets": ["sensu/sensu-influxdb-handler"], + "timeout": 0, + "type": "pipe" +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/handlers/influx-db +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#handlershandler-put-specification} + +/handlers/:handler (PUT) | +----------------|------ +description | Creates or updates the specified Sensu handler. +example URL | http://hostname:8080/api/core/v2/namespaces/default/handlers/influx-db +payload | {{< code shell >}} +{ + "metadata": { + "name": "influx-db", + "namespace": "default", + "labels": null, + "annotations": null + }, + "command": "sensu-influxdb-handler -d sensu", + "env_vars": [ + "INFLUXDB_ADDR=http://influxdb.default.svc.cluster.local:8086", + "INFLUXDB_USER=sensu", + "INFLUXDB_PASSWORD=password" + ], + "filters": [], + "handlers": [], + "runtime_assets": [], + "timeout": 0, + "type": "pipe" +} +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Update a handler with PATCH + +The `/handlers/:handler` API endpoint provides HTTP PATCH access to update `:handler` definitions, specified by handler name. + +{{% notice note %}} +**NOTE**: You cannot change a resource's `name` or `namespace` with a PATCH request. +Use a [PUT request](#handlershandler-put) instead.

    +Also, you cannot add elements to an array with a PATCH request — you must replace the entire array. +{{% /notice %}} + +### Example + +In the following example, an HTTP PATCH request is submitted to the `/handlers/:handler` API endpoint to update the filters array for the `influx-db` handler, resulting in an `HTTP/1.1 200 OK` response and the updated handler definition. + +We support [JSON merge patches][4], so you must set the `Content-Type` header to `application/merge-patch+json` for PATCH requests. + +{{< code shell >}} +curl -X PATCH \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/merge-patch+json' \ +-d '{ + "filters": [ + "us-west", + "is_incident" + ] +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/handlers/influx-db +{{< /code >}} + +### API Specification + +/handlers/:handler (PATCH) | +----------------|------ +description | Updates the specified Sensu handler. +example URL | http://hostname:8080/api/core/v2/namespaces/default/handlers/influx-db +payload | {{< code shell >}} +{ + "filters": [ + "us-west", + "is_incident" + ] +} +{{< /code >}} +response codes |
    • **Success**: 200 (OK)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Delete a handler {#handlershandler-delete} + +The `/handlers/:handler` API endpoint provides HTTP DELETE access to delete a handler from Sensu (specified by the handler name). + +### Example {#handlershandler-delete-example} + +The following example shows a request to the `/handlers/:handler` API endpoint to delete the handler `slack`, which will result in a successful `HTTP/1.1 204 No Content` response. + +{{< code shell >}} +curl -X DELETE \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/handlers/slack \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +### API Specification {#handlershandler-delete-specification} + +/handlers/:handler (DELETE) | +--------------------------|------ +description | Removes the specified handler from Sensu. +example url | http://hostname:8080/api/core/v2/namespaces/default/handlers/slack +response codes |
    • **Success**: 204 (No Content)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + +## Get a subset of handlers with response filtering + +The `/handlers` API endpoint supports [response filtering][3] for a subset of handler data based on labels and the following fields: + +- `handler.name` +- `handler.namespace` +- `handler.filters` +- `handler.handlers` +- `handler.mutator` +- `handler.type` + +### Example + +The following example demonstrates a request to the `/handlers` API endpoint with [response filtering][3] for only [handler definitions][1] in the `default` namespace **and** whose filters include `state_change_only`: + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/handlers -G \ +--data-urlencode 'fieldSelector=state_change_only in handler.filters && handler.namespace == default' +{{< /code >}} + +The example request will result in a successful `HTTP/1.1 200 OK` response and a JSON array that contains only [handler definitions][1] in the `default` namespace **and** whose filters include `state_change_only`: + +{{< code text >}} +[ + { + "metadata": { + "name": "slack", + "namespace": "default", + "created_by": "admin" + }, + "type": "pipe", + "command": "sensu-slack-handler --channel '#monitoring'", + "timeout": 0, + "handlers": null, + "filters": [ + "state_change_only" + ], + "env_vars": null, + "runtime_assets": [ + "sensu-slack-handler" + ], + "secrets": [ + { + "name": "SLACK_WEBHOOK_URL", + "secret": "slack_webhook_url" + } + ] + } +] +{{< /code >}} + +{{% notice note %}} +**NOTE**: Read [API response filtering](../../#response-filtering) for more filter statement examples that demonstrate how to filter responses using different operators with label and field selectors. +{{% /notice %}} + +### API Specification + +/handlers (GET) with response filters | +---------------|------ +description | Returns the list of handlers that match the [response filters][3] applied in the API request. +example url | http://hostname:8080/api/core/v2/handlers +pagination | This endpoint supports [pagination][2] using the `limit` and `continue` query parameters. +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "metadata": { + "name": "slack", + "namespace": "default", + "created_by": "admin" + }, + "type": "pipe", + "command": "sensu-slack-handler --channel '#monitoring'", + "timeout": 0, + "handlers": null, + "filters": [ + "state_change_only" + ], + "env_vars": null, + "runtime_assets": [ + "sensu-slack-handler" + ], + "secrets": [ + { + "name": "SLACK_WEBHOOK_URL", + "secret": "slack_webhook_url" + } + ] + } +] +{{< /code >}} + + +[1]: ../../../observability-pipeline/observe-process/handlers/ +[2]: ../../#pagination +[3]: ../../#response-filtering +[4]: https://tools.ietf.org/html/rfc7396 diff --git a/content/sensu-go/6.12/api/core/hooks.md b/content/sensu-go/6.12/api/core/hooks.md new file mode 100644 index 0000000000..a6e20ab9f3 --- /dev/null +++ b/content/sensu-go/6.12/api/core/hooks.md @@ -0,0 +1,406 @@ +--- +title: "core/v2/hooks" +description: "Read this API documentation for information about Sensu core/v2/hooks API endpoints, with examples for retrieving and managing hooks." +core_api_title: "core/v2/hooks" +type: "core_api" +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: core +--- + +{{% notice note %}} +**NOTE**: Requests to `core/v2/hooks` API endpoints require you to authenticate with a Sensu [API key](../../#configure-an-environment-variable-for-api-key-authentication) or [access token](../../#authenticate-with-auth-api-endpoints). +The code examples in this document use the [environment variable](../../#configure-an-environment-variable-for-api-key-authentication) `$SENSU_API_KEY` to represent a valid API key in API requests. +{{% /notice %}} + +## Get all hooks + +The `/hooks` API endpoint provides HTTP GET access to [hook][1] data. + +### Example {#hooks-get-example} + +The following example demonstrates a GET request to the `/hooks` API endpoint: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/hooks \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request results in a successful `HTTP/1.1 200 OK` response and a JSON array that contains the [hook definitions][1] in the `default` namespace: + +{{< code text >}} +[ + { + "metadata": { + "name": "nginx-log", + "namespace": "default", + "created_by": "admin" + }, + "command": "tail -n 100 /var/log/nginx/error.log", + "timeout": 10, + "stdin": false, + "runtime_assets": null + }, + { + "metadata": { + "name": "process-tree", + "namespace": "default", + "created_by": "admin" + }, + "command": "ps -eo user,pid,cmd:50,%cpu --sort=-%cpu | head -n 6", + "timeout": 10, + "stdin": false, + "runtime_assets": null + } +] +{{< /code >}} + +### API Specification {#hooks-get-specification} + +/hooks (GET) | +---------------|------ +description | Returns the list of hooks. +example url | http://hostname:8080/api/core/v2/namespaces/default/hooks +pagination | This endpoint supports [pagination][2] using the `limit` and `continue` query parameters. +response filtering | This endpoint supports [API response filtering][3]. +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "metadata": { + "name": "nginx-log", + "namespace": "default", + "created_by": "admin" + }, + "command": "tail -n 100 /var/log/nginx/error.log", + "timeout": 10, + "stdin": false, + "runtime_assets": null + }, + { + "metadata": { + "name": "process-tree", + "namespace": "default", + "created_by": "admin" + }, + "command": "ps -eo user,pid,cmd:50,%cpu --sort=-%cpu | head -n 6", + "timeout": 10, + "stdin": false, + "runtime_assets": null + } +] +{{< /code >}} + +## Create a new hook + +The `/hooks` API endpoint provides HTTP POST access to create a hook. + +### Example {#hooks-post-example} + +In the following example, an HTTP POST request is submitted to the `/hooks` API endpoint to create the hook `process-tree`: + +{{< code shell >}} +curl -X POST \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "metadata": { + "name": "process-tree", + "namespace": "default", + "labels": null, + "annotations": null + }, + "command": "ps -eo user,pid,cmd:50,%cpu --sort=-%cpu | head -n 6", + "timeout": 10, + "stdin": false +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/hooks +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#hooks-post-specification} + +/hooks (POST) | +----------------|------ +description | Creates a Sensu hook. +example URL | http://hostname:8080/api/core/v2/namespaces/default/hooks +payload | {{< code shell >}} +{ + "metadata": { + "name": "process-tree", + "namespace": "default", + "labels": null, + "annotations": null + }, + "command": "ps aux", + "timeout": 10, + "stdin": false +} +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Get a specific hook {#hookshook-get} + +The `/hooks/:hook` API endpoint provides HTTP GET access to [hook data][1] for specific `:hook` definitions, by hook name. + +### Example {#hookshook-get-example} + +The following example queries the `/hooks/:hook` API endpoint for the `:hook` named `process-tree`: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/hooks/process-tree \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request will return a successful `HTTP/1.1 200 OK` response and a JSON map that contains the requested [`:hook` definition][1] (in this example, `process-tree`): + +{{< code text >}} +{ + "metadata": { + "name": "process-tree", + "namespace": "default", + "created_by": "admin", + "labels": null, + "annotations": null + }, + "command": "ps aux", + "timeout": 10, + "stdin": false +} +{{< /code >}} + +### API Specification {#hookshook-get-specification} + +/hooks/:hook (GET) | +---------------------|------ +description | Returns the specified hook. +example url | http://hostname:8080/api/core/v2/namespaces/default/hooks/process-tree +response type | Map +response codes |
    • **Success**: 200 (OK)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +{ + "metadata": { + "name": "process-tree", + "namespace": "default", + "created_by": "admin", + "labels": null, + "annotations": null + }, + "command": "ps aux", + "timeout": 10, + "stdin": false +} +{{< /code >}} + +## Create or update a hook {#hookshook-put} + +The `/hooks/:hook` API endpoint provides HTTP PUT access to create or update specific `:hook` definitions, by hook name. + +### Example {#hooks-put-example} + +In the following example, an HTTP PUT request is submitted to the `/hooks/:hook` API endpoint to create the hook `nginx-log`: + +{{< code shell >}} +curl -X PUT \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "metadata": { + "name": "nginx-log", + "namespace": "default", + "labels": null, + "annotations": null + }, + "command": "tail -n 100 /var/log/nginx/error.log", + "timeout": 10, + "stdin": false + }' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/hooks/nginx-log +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#hookshook-put-specification} + +/hooks/:hook (PUT) | +----------------|------ +description | Creates or updates the specified Sensu hook. +example URL | http://hostname:8080/api/core/v2/namespaces/default/hooks/nginx-log +payload | {{< code shell >}} +{ + "metadata": { + "name": "nginx-log", + "namespace": "default", + "labels": null, + "annotations": null + }, + "command": "tail -n 100 /var/log/nginx/error.log", + "timeout": 10, + "stdin": false + } +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Update a hook with PATCH + +The `/hooks/:hook` API endpoint provides HTTP PATCH access to update `:hook` definitions, specified by hook name. + +{{% notice note %}} +**NOTE**: You cannot change a resource's `name` or `namespace` with a PATCH request. +Use a [PUT request](#hookshook-put) instead.

    +Also, you cannot add elements to an array with a PATCH request — you must replace the entire array. +{{% /notice %}} + +### Example + +In the following example, an HTTP PATCH request is submitted to the `/hooks/:hook` API endpoint to update the timeout for the `process-tree` hook, resulting in an `HTTP/1.1 200 OK` response and the updated hook definition. + +We support [JSON merge patches][4], so you must set the `Content-Type` header to `application/merge-patch+json` for PATCH requests. + +{{< code shell >}} +curl -X PATCH \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/merge-patch+json' \ +-d '{ + "timeout": 20 +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/hook/process-tree +{{< /code >}} + +### API Specification + +/hooks/:hook (PATCH) | +----------------|------ +description | Updates the specified Sensu hook. +example URL | http://hostname:8080/api/core/v2/namespaces/default/hooks/process-tree +payload | {{< code shell >}} +{ + "timeout": 20 +} +{{< /code >}} +response codes |
    • **Success**: 200 (OK)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Delete a hook {#hookshook-delete} + +The `/hooks/:hook` API endpoint provides HTTP DELETE access to delete a check hook from Sensu (specified by the hook name). + +### Example {#hookshook-delete-example} + +The following example shows a request to the `/hooks/:hook` API endpoint to delete the hook `process-tree`, resulting in a successful `HTTP/1.1 204 No Content` response: + +{{< code shell >}} +curl -X DELETE \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/hooks/process-tree \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +### API Specification {#hookshook-delete-specification} + +/hooks/:hook (DELETE) | +--------------------------|------ +description | Removes the specified hook from Sensu. +example url | http://hostname:8080/api/core/v2/namespaces/default/hooks/process-tree +response codes |
    • **Success**: 204 (No Content)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + +## Get a subset of hooks with response filtering + +The `/hooks` API endpoint supports [response filtering][3] for a subset of hook data based on labels and the following fields: + +- `hook.name` +- `hook.namespace` + +### Example + +The following example demonstrates a request to the `/hooks` API endpoint with [response filtering][3] for only [hook definitions][1] in the `production` namespace: + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/hooks -G \ +--data-urlencode 'fieldSelector=hook.namespace == production' +{{< /code >}} + +The example request will result in a successful `HTTP/1.1 200 OK` response and a JSON array that contains only [hook definitions][1] in the `production` namespace: + +{{< code text >}} +[ + { + "metadata": { + "name": "process_tree", + "namespace": "production", + "created_by": "admin" + }, + "command": "ps aux", + "timeout": 10, + "stdin": false, + "runtime_assets": null + }, + { + "metadata": { + "name": "restart_nginx", + "namespace": "production", + "labels": { + "sensu.io/managed_by": "sensuctl" + }, + "created_by": "admin" + }, + "command": "sudo systemctl start nginx", + "timeout": 60, + "stdin": false, + "runtime_assets": null + } +] +{{< /code >}} + +{{% notice note %}} +**NOTE**: Read [API response filtering](../../#response-filtering) for more filter statement examples that demonstrate how to filter responses using different operators with label and field selectors. +{{% /notice %}} + +### API Specification + +/hooks (GET) with response filters | +---------------|------ +description | Returns the list of hooks that match the [response filters][3] applied in the API request. +example url | http://hostname:8080/api/core/v2/hooks +pagination | This endpoint supports [pagination][2] using the `limit` and `continue` query parameters. +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "metadata": { + "name": "process_tree", + "namespace": "production", + "created_by": "admin" + }, + "command": "ps aux", + "timeout": 10, + "stdin": false, + "runtime_assets": null + }, + { + "metadata": { + "name": "restart_nginx", + "namespace": "production", + "labels": { + "sensu.io/managed_by": "sensuctl" + }, + "created_by": "admin" + }, + "command": "sudo systemctl start nginx", + "timeout": 60, + "stdin": false, + "runtime_assets": null + } +] +{{< /code >}} + + +[1]: ../../../observability-pipeline/observe-schedule/hooks/ +[2]: ../../#pagination +[3]: ../../#response-filtering +[4]: https://tools.ietf.org/html/rfc7396 diff --git a/content/sensu-go/6.12/api/core/mutators.md b/content/sensu-go/6.12/api/core/mutators.md new file mode 100644 index 0000000000..2f749ad5ad --- /dev/null +++ b/content/sensu-go/6.12/api/core/mutators.md @@ -0,0 +1,428 @@ +--- +title: "core/v2/mutators" +description: "Read this API documentation for information about Sensu core/v2/mutators API endpoints, with examples for retrieving and managing mutators." +core_api_title: "core/v2/mutators" +type: "core_api" +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: core +--- + +{{% notice note %}} +**NOTE**: Requests to `core/v2/mutators` API endpoints require you to authenticate with a Sensu [API key](../../#configure-an-environment-variable-for-api-key-authentication) or [access token](../../#authenticate-with-auth-api-endpoints). +The code examples in this document use the [environment variable](../../#configure-an-environment-variable-for-api-key-authentication) `$SENSU_API_KEY` to represent a valid API key in API requests. +{{% /notice %}} + +## Get all mutators + +The `/mutators` API endpoint provides HTTP GET access to [mutator][1] data. + +### Example {#mutators-get-example} + +The following example demonstrates a GET request to the `/mutators` API endpoint: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/mutators \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request results in a successful `HTTP/1.1 200 OK` response and a JSON array that contains the [mutator definitions][1] in the `default` namespace: + +{{< code text >}} +[ + { + "metadata": { + "name": "example-mutator", + "namespace": "default", + "created_by": "admin", + "labels": null, + "annotations": null + }, + "command": "example_mutator.go", + "timeout": 0, + "env_vars": [], + "runtime_assets": [], + "secrets": null, + "type": "pipe" + } +] +{{< /code >}} + +### API Specification {#mutators-get-specification} + +/mutators (GET) | +---------------|------ +description | Returns the list of mutators. +example url | http://hostname:8080/api/core/v2/namespaces/default/mutators +pagination | This endpoint supports [pagination][2] using the `limit` and `continue` query parameters. +response filtering | This endpoint supports [API response filtering][3]. +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "metadata": { + "name": "example-mutator", + "namespace": "default", + "created_by": "admin", + "labels": null, + "annotations": null + }, + "command": "example_mutator.go", + "timeout": 0, + "env_vars": [], + "runtime_assets": [], + "secrets": null, + "type": "pipe" + } +] +{{< /code >}} + +## Create a new mutator + +The `/mutators` API endpoint provides HTTP POST access to create mutators. + +### Example {#mutators-post-example} + +In the following example, an HTTP POST request is submitted to the `/mutators` API endpoint to create the mutator `example-mutator`: + +{{< code shell >}} +curl -X POST \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "metadata": { + "name": "example-mutator", + "namespace": "default", + "labels": null, + "annotations": null + }, + "command": "example_mutator.go", + "timeout": 0, + "env_vars": [], + "runtime_assets": [], + "secrets": null, + "type": "pipe" +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/mutators +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#mutators-post-specification} + +/mutators (POST) | +----------------|------ +description | Creates a Sensu mutator. +example URL | http://hostname:8080/api/core/v2/namespaces/default/mutators +payload | {{< code shell >}} +{ + "metadata": { + "name": "example-mutator", + "namespace": "default", + "labels": null, + "annotations": null + }, + "command": "example_mutator.go", + "timeout": 0, + "env_vars": [], + "runtime_assets": [], + "secrets": null, + "type": "pipe" +} +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Get a specific mutator {#mutatorsmutator-get} + +The `/mutators/:mutator` API endpoint provides HTTP GET access to [mutator data][1] for specific `:mutator` definitions, by mutator name. + +### Example {#mutatorsmutator-get-example} + +The following example queries the `/mutators/:mutator` API endpoint for the `:mutator` named `example-mutator`: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/mutators/example-mutator \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request will return a successful `HTTP/1.1 200 OK` response and a JSON map that contains the requested [`:mutator` definition][1] (in this example, `example-mutator`): + +{{< code text >}} +{ + "metadata": { + "name": "example-mutator", + "namespace": "default", + "created_by": "admin", + "labels": null, + "annotations": null + }, + "command": "example_mutator.go", + "timeout": 0, + "env_vars": [], + "runtime_assets": [], + "secrets": null, + "type": "pipe" +} +{{< /code >}} + +### API Specification {#mutatorsmutator-get-specification} + +/mutators/:mutator (GET) | +---------------------|------ +description | Returns the specified mutator. +example url | http://hostname:8080/api/core/v2/namespaces/default/mutators/example-mutator +response type | Map +response codes |
    • **Success**: 200 (OK)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +{ + "metadata": { + "name": "example-mutator", + "namespace": "default", + "created_by": "admin", + "labels": null, + "annotations": null + }, + "command": "example_mutator.go", + "timeout": 0, + "env_vars": [], + "runtime_assets": [], + "secrets": null, + "type": "pipe" +} +{{< /code >}} + +## Create or update a mutator {#mutatorsmutator-put} + +The `/mutators/:mutator` API endpoint provides HTTP PUT access to [mutator data][1] to create or update specific `:mutator` definitions, by mutator name. + +### Example {#mutatorsmutator-put-example} + +In the following example, an HTTP PUT request is submitted to the `/mutators/:mutator` API endpoint to create the mutator `example-mutator`: + +{{< code shell >}} +curl -X PUT \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "metadata": { + "name": "example-mutator", + "namespace": "default", + "labels": null, + "annotations": null + }, + "command": "example_mutator.go", + "timeout": 0, + "env_vars": [], + "runtime_assets": [], + "secrets": null, + "type": "pipe" +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/mutators/example-mutator +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#mutatorsmutator-put-specification} + +/mutators/:mutator (PUT) | +----------------|------ +description | Creates or updates a Sensu mutator. +example URL | http://hostname:8080/api/core/v2/namespaces/default/mutators/example-mutator +payload | {{< code shell >}} +{ + "metadata": { + "name": "example-mutator", + "namespace": "default", + "labels": null, + "annotations": null + }, + "command": "example_mutator.go", + "timeout": 0, + "env_vars": [], + "runtime_assets": [], + "secrets": null, + "type": "pipe" +} +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Update a mutator with PATCH + +The `/mutators/:mutator` API endpoint provides HTTP PATCH access to update `:mutator` definitions, specified by mutator name. + +{{% notice note %}} +**NOTE**: You cannot change a resource's `name` or `namespace` with a PATCH request. +Use a [PUT request](#mutatorsmutator-put) instead.

    +Also, you cannot add elements to an array with a PATCH request — you must replace the entire array. +{{% /notice %}} + +### Example + +In the following example, an HTTP PATCH request is submitted to the `/mutators/:mutator` API endpoint to update the timeout for the `example-mutator` mutator, resulting in an `HTTP/1.1 200 OK` response and the updated mutator definition. + +We support [JSON merge patches][4], so you must set the `Content-Type` header to `application/merge-patch+json` for PATCH requests. + +{{< code shell >}} +curl -X PATCH \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/merge-patch+json' \ +-d '{ + "timeout": 10 +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/mutators/example-mutator +{{< /code >}} + +### API Specification + +/mutators/:mutator (PATCH) | +----------------|------ +description | Updates the specified Sensu mutator. +example URL | http://hostname:8080/api/core/v2/namespaces/default/mutators/process-tree +payload | {{< code shell >}} +{ + "timeout": 10 +} +{{< /code >}} +response codes |
    • **Success**: 200 (OK)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Delete a mutator {#mutatorsmutator-delete} + +The `/mutators/:mutator` API endpoint provides HTTP DELETE access to delete a mutator from Sensu (specified by the mutator name). + +### Example {#mutatorsmutator-delete-example} +The following example shows a request to the `/mutators/:mutator` API endpoint to delete the mutator `example-mutator`, resulting in a successful `HTTP/1.1 204 No Content` response. + +{{< code shell >}} +curl -X DELETE \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/mutators/example-mutator \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +### API Specification {#mutatorsmutator-delete-specification} + +/mutators/:mutator (DELETE) | +--------------------------|------ +description | Removes the specified mutator from Sensu. +example url | http://hostname:8080/api/core/v2/namespaces/default/mutators/example-mutator +response codes |
    • **Success**: 204 (No Content)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + +## Get a subset of mutators with response filtering + +The `/mutators` API endpoint supports [response filtering][3] for a subset of mutator data based on labels and the following fields: + +- `mutator.name` +- `mutator.namespace` +- `mutator.runtime_assets` + +### Example + +The following example demonstrates a request to the `/mutators` API endpoint with [response filtering][3] for only [mutator definitions][1] that are in the `production` namespace: + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/mutators -G \ +--data-urlencode 'fieldSelector=mutator.namespace == production' +{{< /code >}} + +The example request will result in a successful `HTTP/1.1 200 OK` response and a JSON array that contains only [mutator definitions][1] in the `production` namespace: + +{{< code text >}} +[ + { + "metadata": { + "name": "add_check_label", + "namespace": "production", + "labels": { + "sensu.io/managed_by": "sensuctl" + }, + "created_by": "admin" + }, + "timeout": 0, + "env_vars": null, + "runtime_assets": null, + "secrets": null, + "type": "javascript", + "eval": "data = JSON.parse(JSON.stringify(event)); delete data.check.metadata.name; delete data.entity.metadata.labels.app_id; return JSON.stringify(data)" + }, + { + "metadata": { + "name": "example-mutator", + "namespace": "production", + "labels": { + "sensu.io/managed_by": "sensuctl" + }, + "created_by": "admin" + }, + "command": "example_mutator.go", + "timeout": 0, + "env_vars": null, + "runtime_assets": [ + "example-mutator-asset" + ], + "secrets": null, + "type": "pipe" + } +] +{{< /code >}} + +{{% notice note %}} +**NOTE**: Read [API response filtering](../../#response-filtering) for more filter statement examples that demonstrate how to filter responses using different operators with label and field selectors. +{{% /notice %}} + +### API Specification + +/mutators (GET) with response filters | +---------------|------ +description | Returns the list of mutators that match the [response filters][3] applied in the API request. +example url | http://hostname:8080/api/core/v2/mutators +pagination | This endpoint supports [pagination][2] using the `limit` and `continue` query parameters. +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "metadata": { + "name": "add_check_label", + "namespace": "production", + "labels": { + "sensu.io/managed_by": "sensuctl" + }, + "created_by": "admin" + }, + "timeout": 0, + "env_vars": null, + "runtime_assets": null, + "secrets": null, + "type": "javascript", + "eval": "data = JSON.parse(JSON.stringify(event)); delete data.check.metadata.name; delete data.entity.metadata.labels.app_id; return JSON.stringify(data)" + }, + { + "metadata": { + "name": "example-mutator", + "namespace": "production", + "labels": { + "sensu.io/managed_by": "sensuctl" + }, + "created_by": "admin" + }, + "command": "example_mutator.go", + "timeout": 0, + "env_vars": null, + "runtime_assets": [ + "example-mutator-asset" + ], + "secrets": null, + "type": "pipe" + } +] +{{< /code >}} + + +[1]: ../../../observability-pipeline/observe-transform/mutators/ +[2]: ../../#pagination +[3]: ../../#response-filtering +[4]: https://tools.ietf.org/html/rfc7396 diff --git a/content/sensu-go/6.12/api/core/namespaces.md b/content/sensu-go/6.12/api/core/namespaces.md new file mode 100644 index 0000000000..e281e8fb70 --- /dev/null +++ b/content/sensu-go/6.12/api/core/namespaces.md @@ -0,0 +1,260 @@ +--- +title: "core/v2/namespaces" +description: "Read this API documentation for information about Sensu core/v2/namespaces API endpoints, with examples for retrieving and managing namespaces." +core_api_title: "core/v2/namespaces" +type: "core_api" +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: core +--- + +{{% notice note %}} +**NOTE**: Requests to `core/v2/namespaces` API endpoints require you to authenticate with a Sensu [API key](../../#configure-an-environment-variable-for-api-key-authentication) or [access token](../../#authenticate-with-auth-api-endpoints). +The code examples in this document use the [environment variable](../../#configure-an-environment-variable-for-api-key-authentication) `$SENSU_API_KEY` to represent a valid API key in API requests. +{{% /notice %}} + +## Get all namespaces + +The `/namespaces` API endpoint provides HTTP GET access to [namespace][1] data. + +### Example {#namespaces-get-example} + +The following example demonstrates a GET request to the `/namespaces` API endpoint: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/core/v2/namespaces \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request results in a successful `HTTP/1.1 200 OK` response and a JSON array that contains [namespace definitions][1]: + +{{< code text >}} +[ + { + "name": "default" + }, + { + "name": "development" + } +] +{{< /code >}} + +### API Specification {#namespaces-get-specification} + +/namespaces (GET) | +---------------|------ +description | Returns the list of namespaces. +example url | http://hostname:8080/api/core/v2/namespaces +pagination | This endpoint supports [pagination][2] using the `limit` and `continue` query parameters. +response filtering | This endpoint supports [API response filtering][3]. +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "name": "default" + }, + { + "name": "development" + } +] +{{< /code >}} + +## Create a new namespace + +The `/namespaces` API endpoint provides HTTP POST access to create Sensu namespaces. + +### Example {#namespaces-post-example} + +In the following example, an HTTP POST request is submitted to the `/namespaces` API endpoint to create the namespace `development`: + +{{< code shell >}} +curl -X POST \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "name": "development" +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#namespaces-post-specification} + +/namespaces (POST) | +----------------|------ +description | Creates a Sensu namespace. +example URL | http://hostname:8080/api/core/v2/namespaces +payload | {{< code shell >}} +{ + "name": "development" +} +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Create or update a namespace {#namespacesnamespace-put} + +The `/namespaces/:namespace` API endpoint provides HTTP PUT access to create or update specific Sensu namespaces, by namespace name. + +### Example {#namespacesnamespace-put-example} + +In the following example, an HTTP PUT request is submitted to the `/namespaces/:namespace` API endpoint to create the namespace `development`: + +{{< code shell >}} +curl -X PUT \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "name": "development" +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/development +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#namespacesnamespace-put-specification} + +/namespaces/:namespace (PUT) | +----------------|------ +description | Creates or updates a Sensu namespace. +example URL | http://hostname:8080/api/core/v2/namespaces/development +payload | {{< code shell >}} +{ + "name": "development" +} +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Delete a namespace {#namespacesnamespace-delete} + +The `/namespaces/:namespace` API endpoint provides HTTP DELETE access to delete a namespace from Sensu (specified by the namespace name). + +### Example {#namespacesnamespace-delete-example} + +The following example shows a request to the `/namespaces/:namespace` API endpoint to delete the namespace `development`, resulting in a successful `HTTP/1.1 204 No Content` response. + +{{< code shell >}} +curl -X DELETE \ +http://127.0.0.1:8080/api/core/v2/namespaces/development \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +Namespaces must be empty before you can delete them. +If the response to your delete request includes `Error: resource is invalid: namespace is not empty`, the namespace may still contain events or other resources. +To remove all resources and events so that you can delete a namespace, use this sensuctl dump command (replace `` with the namespace you want to empty): + +{{< code shell >}} +sensuctl dump entities,events,assets,checks,filters,handlers,secrets/v1.Secret --namespace | sensuctl delete +{{< /code >}} + +### API Specification {#namespacesnamespace-delete-specification} + +/namespaces/:namespace (DELETE) | +--------------------------|------ +description | Removes the specified namespace from Sensu. +example url | http://hostname:8080/api/core/v2/namespaces/development +response codes |
    • **Success**: 204 (No Content)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + +## Get a subset of namespaces with response filtering + +The `/namespaces` API endpoint supports [response filtering][3] for a subset of namespace data based on labels and the field `namespace.name`. + +### Example + +The following example demonstrates a request to the `/namespaces` API endpoint with [response filtering][3] for only the [namespace definitions][1] for the `production` namespace: + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/namespaces -G \ +--data-urlencode 'fieldSelector=namespace.name == production' +{{< /code >}} + +The example request will result in a successful `HTTP/1.1 200 OK` response and a JSON array that contains only [namespace definitions][1] for the `production` namespace: + +{{< code text >}} +[ + { + "name": "production" + } +] +{{< /code >}} + +{{% notice note %}} +**NOTE**: Read [API response filtering](../../#response-filtering) for more filter statement examples that demonstrate how to filter responses using different operators with label and field selectors. +{{% /notice %}} + +### API Specification + +/namespaces (GET) with response filters | +---------------|------ +description | Returns the list of namespaces that match the [response filters][3] applied in the API request. +example url | http://hostname:8080/api/core/v2/namespaces +pagination | This endpoint supports [pagination][2] using the `limit` and `continue` query parameters. +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "name": "production" + } +] +{{< /code >}} + +## Get all namespaces for a specific user + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access the `/user-namespaces` API endpoint in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} + +The `/user-namespaces` API endpoint provides HTTP GET access to the namespaces the current user can access. + +### Example {#user-namespaces-get-example} + +The following example demonstrates a GET request to the `/user-namespaces` API endpoint: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/enterprise/user-namespaces \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The example request will result in a successful `HTTP/1.1 200 OK` response and a JSON array that contains only the namespaces the current user can access: + +{{< code text >}} +[ + { + "name": "default" + }, + { + "name": "development" + } +] +{{< /code >}} + +### API Specification {#namespaces-get-specification} + +/user-namespaces (GET) | +---------------|------ +description | Returns the list of namespaces a user has access to. +example url | http://hostname:8080/api/enterprise/user-namespaces +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "name": "default" + }, + { + "name": "development" + } +] +{{< /code >}} + + +[1]: ../../../operations/control-access/namespaces/ +[2]: ../../#pagination +[3]: ../../#response-filtering diff --git a/content/sensu-go/6.12/api/core/pipelines.md b/content/sensu-go/6.12/api/core/pipelines.md new file mode 100644 index 0000000000..4a39827f49 --- /dev/null +++ b/content/sensu-go/6.12/api/core/pipelines.md @@ -0,0 +1,703 @@ +--- +title: "core/v2/pipelines" +description: "Read this API documentation for information about Sensu core/v2/pipelines API endpoints, with examples for retrieving and managing pipelines." +core_api_title: "core/v2/pipelines" +type: "core_api" +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: core +--- + +{{% notice warning %}} +**IMPORTANT**: The [pipelines](../../../observability-pipeline/observe-process/pipelines/) you can create and manage with this `core/v2/pipelines` API are observation event processing workflows made up of filters, mutators, and handlers.

    +Pipelines are different from the resources you can create and manage with the [`enterprise/pipeline/v1`](../../enterprise/pipeline/) API, which allows you to create and manage resources that can **only** be used in pipelines. +{{% /notice %}} + +{{% notice note %}} +**NOTE**: Requests to `core/v2/pipelines` API endpoints require you to authenticate with a Sensu [API key](../../#configure-an-environment-variable-for-api-key-authentication) or [access token](../../#authenticate-with-auth-api-endpoints). +The code examples in this document use the [environment variable](../../#configure-an-environment-variable-for-api-key-authentication) `$SENSU_API_KEY` to represent a valid API key in API requests. +{{% /notice %}} + +## Get all pipelines + +The `/pipelines` API endpoint provides HTTP GET access to [pipeline][1] data. + +### Example + +The following example demonstrates a GET request to the `/pipelines` API endpoint: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/pipelines \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request results in a successful `HTTP/1.1 200 OK` response and a JSON array that contains the [pipeline definitions][1] in the `default` namespace: + +{{< code text >}} +[ + { + "metadata": { + "name": "labeled_emails", + "namespace": "default", + "created_by": "admin" + }, + "workflows": [ + { + "name": "default", + "filters": [ + { + "name": "is_incident", + "type": "EventFilter", + "api_version": "core/v2" + }, + { + "name": "state_change_only", + "type": "EventFilter", + "api_version": "core/v2" + } + ], + "mutator": { + "name": "add_labels", + "type": "Mutator", + "api_version": "core/v2" + }, + "handler": { + "name": "email", + "type": "Handler", + "api_version": "core/v2" + } + } + ] + }, + { + "metadata": { + "name": "slack_pipeline", + "namespace": "default", + "created_by": "admin" + }, + "workflows": [ + { + "name": "default", + "filters": [ + { + "name": "is_incident", + "type": "EventFilter", + "api_version": "core/v2" + }, + { + "name": "state_change_only", + "type": "EventFilter", + "api_version": "core/v2" + } + ], + "mutator": { + "name": "add_labels", + "type": "Mutator", + "api_version": "core/v2" + }, + "handler": { + "name": "slack", + "type": "Handler", + "api_version": "core/v2" + } + } + ] + } +] +{{< /code >}} + +### API Specification + +/pipelines (GET) | +---------------|------ +description | Returns the list of pipelines. +example url | http://hostname:8080/api/core/v2/namespaces/default/pipelines +pagination | This endpoint supports [pagination][2] using the `limit` and `continue` query parameters. +response filtering | This endpoint supports [API response filtering][3]. +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "metadata": { + "name": "labeled_emails", + "namespace": "default", + "created_by": "admin" + }, + "workflows": [ + { + "name": "default", + "filters": [ + { + "name": "is_incident", + "type": "EventFilter", + "api_version": "core/v2" + }, + { + "name": "state_change_only", + "type": "EventFilter", + "api_version": "core/v2" + } + ], + "mutator": { + "name": "add_labels", + "type": "Mutator", + "api_version": "core/v2" + }, + "handler": { + "name": "email", + "type": "Handler", + "api_version": "core/v2" + } + } + ] + }, + { + "metadata": { + "name": "slack_pipeline", + "namespace": "default", + "created_by": "admin" + }, + "workflows": [ + { + "name": "default", + "filters": [ + { + "name": "is_incident", + "type": "EventFilter", + "api_version": "core/v2" + }, + { + "name": "state_change_only", + "type": "EventFilter", + "api_version": "core/v2" + } + ], + "mutator": { + "name": "add_labels", + "type": "Mutator", + "api_version": "core/v2" + }, + "handler": { + "name": "slack", + "type": "Handler", + "api_version": "core/v2" + } + } + ] + } +] +{{< /code >}} + +## Create a new pipeline + +The `/pipelines` API endpoint provides HTTP POST access to create a pipeline. + +### Example + +In the following example, an HTTP POST request is submitted to the `/pipelines` API endpoint to create the pipeline resource `labeled_emails`: + +{{< code shell >}} +curl -X POST \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "metadata": { + "name": "labeled_emails", + "namespace": "default" + }, + "workflows": [ + { + "name": "default", + "filters": [ + { + "api_version": "core/v2", + "type": "EventFilter", + "name": "is_incident" + }, + { + "api_version": "core/v2", + "type": "EventFilter", + "name": "state_change_only" + } + ], + "mutator": { + "api_version": "core/v2", + "type": "Mutator", + "name": "add_labels" + }, + "handler": { + "api_version": "core/v2", + "type": "Handler", + "name": "email" + } + } + ] +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/pipelines +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification + +/pipelines (POST) | +----------------|------ +description | Creates a Sensu pipeline. +example URL | http://hostname:8080/api/core/v2/namespaces/default/pipelines +payload | {{< code shell >}} +{ + "metadata": { + "name": "labeled_email", + "namespace": "default" + }, + "workflows": [ + { + "name": "default", + "filters": [ + { + "api_version": "core/v2", + "type": "EventFilter", + "name": "is_incident" + }, + { + "api_version": "core/v2", + "type": "EventFilter", + "name": "state_change_only" + } + ], + "mutator": { + "api_version": "core/v2", + "type": "Mutator", + "name": "add_labels" + }, + "handler": { + "api_version": "core/v2", + "type": "Handler", + "name": "email" + } + } + ] +} +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Get a specific pipeline + +The `/pipelines/:pipeline` API endpoint provides HTTP GET access to [pipeline data][1] for specific `:pipeline` definitions, by pipeline name. + +### Example + +The following example queries the `/pipelines/:pipeline` API endpoint for the `:pipeline` named `labeled_emails`: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/pipelines/labeled_emails \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request will return a successful `HTTP/1.1 200 OK` response and a JSON map that contains the requested [`:pipeline` definition][1] (in this example, `labeled_emails`): + +{{< code text >}} +{ + "metadata": { + "name": "labeled_emails", + "namespace": "default", + "created_by": "admin" + }, + "workflows": [ + { + "name": "default", + "filters": [ + { + "name": "is_incident", + "type": "EventFilter", + "api_version": "core/v2" + }, + { + "name": "state_change_only", + "type": "EventFilter", + "api_version": "core/v2" + } + ], + "mutator": { + "name": "add_labels", + "type": "Mutator", + "api_version": "core/v2" + }, + "handler": { + "name": "email", + "type": "Handler", + "api_version": "core/v2" + } + } + ] +} +{{< /code >}} + +### API Specification + +/pipelines/:pipeline (GET) | +---------------------|------ +description | Returns a pipeline. +example url | http://hostname:8080/api/core/v2/namespaces/default/pipelines/labeled_emails +response type | Map +response codes |
    • **Success**: 200 (OK)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +{ + "metadata": { + "name": "labeled_emails", + "namespace": "default", + "created_by": "admin" + }, + "workflows": [ + { + "name": "default", + "filters": [ + { + "name": "is_incident", + "type": "EventFilter", + "api_version": "core/v2" + }, + { + "name": "state_change_only", + "type": "EventFilter", + "api_version": "core/v2" + } + ], + "mutator": { + "name": "add_labels", + "type": "Mutator", + "api_version": "core/v2" + }, + "handler": { + "name": "email", + "type": "Handler", + "api_version": "core/v2" + } + } + ] +} +{{< /code >}} + +## Create or update a pipeline + +The `/pipelines/:pipeline` API endpoint provides HTTP PUT access to create or update a specific `:pipeline` definition, by pipeline name. + +### Example + +In the following example, an HTTP PUT request is submitted to the `/pipelines/:pipeline` API endpoint to update `slack_pipeline` to use `javascript_mutator` instead of the `add_labels` mutator: + +{{< code shell >}} +curl -X PUT \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "metadata": { + "name": "slack_pipeline", + "namespace": "default" + }, + "workflows": [ + { + "name": "default", + "filters": [ + { + "api_version": "core/v2", + "type": "EventFilter", + "name": "is_incident" + }, + { + "api_version": "core/v2", + "type": "EventFilter", + "name": "state_change_only" + } + ], + "mutator": { + "api_version": "core/v2", + "type": "Mutator", + "name": "javascript_mutator" + }, + "handler": { + "api_version": "core/v2", + "type": "Handler", + "name": "slack" + } + } + ] +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/pipelines/slack_pipeline +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification + +/pipelines/:pipeline (PUT) | +----------------|------ +description | Creates or updates the specified Sensu pipeline. +example URL | http://hostname:8080/api/core/v2/namespaces/default/pipelines/slack_pipeline +payload | {{< code shell >}} +{ + "metadata": { + "name": "slack_pipeline", + "namespace": "default" + }, + "workflows": [ + { + "name": "default", + "filters": [ + { + "api_version": "core/v2", + "type": "EventFilter", + "name": "is_incident" + }, + { + "api_version": "core/v2", + "type": "EventFilter", + "name": "state_change_only" + } + ], + "mutator": { + "api_version": "core/v2", + "type": "Mutator", + "name": "javascript_mutator" + }, + "handler": { + "api_version": "core/v2", + "type": "Handler", + "name": "slack" + } + } + ] +} +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Update a pipeline with PATCH + +The `/pipelines/:pipeline` API endpoint provides HTTP PATCH access to update `:pipeline` definitions, specified by pipeline name. + +{{% notice note %}} +**NOTE**: You cannot change a resource's `name` or `namespace` with a PATCH request. +Use a [PUT request](#create-or-update-a-pipeline) instead.

    +Also, you cannot add elements to an array with a PATCH request — you must replace the entire array. +{{% /notice %}} + +### Example + +In the following example, an HTTP PATCH request is submitted to the `/pipelines/:pipeline` API endpoint to update the mutator for `slack_pipeline`, resulting in an `HTTP/1.1 200 OK` response and the updated pipeline definition. + +We support [JSON merge patches][4], so you must set the `Content-Type` header to `application/merge-patch+json` for PATCH requests. + +{{< code shell >}} +curl -X PATCH \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/merge-patch+json' \ +-d '{ + "workflows": [ + { + "mutator": { + "api_version": "core/v2", + "type": "Mutator", + "name": "javascript_mutator_2" + } + } + ] +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/pipelines/slack_pipeline +{{< /code >}} + +### API Specification + +/pipelines/:pipeline (PATCH) | +----------------|------ +description | Updates the specified Sensu pipeline. +example URL | http://hostname:8080/api/core/v2/namespaces/default/pipelines/slack_pipeline +payload | {{< code shell >}} +{ + "workflows": [ + { + "mutator": { + "api_version": "core/v2", + "type": "Mutator", + "name": "javascript_mutator" + } + } + ] +} +{{< /code >}} +response codes |
    • **Success**: 200 (OK)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Delete a pipeline + +The `/pipelines/:pipeline` API endpoint provides HTTP DELETE access to delete a pipeline from Sensu (specified by the pipeline name). + +### Example + +The following example shows a request to the `/pipelines/:pipeline` API endpoint to delete `slack_pipeline`, resulting in a successful `HTTP/1.1 204 No Content` response: + +{{< code shell >}} +curl -X DELETE \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/pipelines/slack_pipeline \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +### API Specification + +/pipelines/:pipeline (DELETE) | +--------------------------|------ +description | Removes the specified pipeline from Sensu. +example url | http://hostname:8080/api/core/v2/namespaces/default/pipelines/slack_pipeline +response codes |
    • **Success**: 204 (No Content)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + +## Get a subset of pipelines with response filtering + +The `/pipelines` API endpoint supports [response filtering][3] for a subset of pipeline data based on labels and the following fields: + +- `pipeline.name` +- `pipeline.namespace` + +### Example + +The following example demonstrates a request to the `/pipelines` API endpoint with [response filtering][3] for only [pipeline definitions][1] in the `production` namespace: + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/pipelines -G \ +--data-urlencode 'fieldSelector=pipeline.namespace == production' +{{< /code >}} + +The example request will result in a successful `HTTP/1.1 200 OK` response and a JSON array that contains only [pipeline definitions][1] in the `production` namespace: + +{{< code text >}} +[ + { + "metadata": { + "name": "sensu_email_alerts", + "namespace": "production", + "created_by": "admin" + }, + "workflows": [ + { + "name": "labeled_email_alerts", + "filters": [ + { + "name": "is_incident", + "type": "EventFilter", + "api_version": "core/v2" + }, + { + "name": "state_change_only", + "type": "EventFilter", + "api_version": "core/v2" + } + ], + "mutator": { + "name": "add_labels", + "type": "Mutator", + "api_version": "core/v2" + }, + "handler": { + "name": "email", + "type": "Handler", + "api_version": "core/v2" + } + } + ] + }, + { + "metadata": { + "name": "sensu_to_sumo", + "namespace": "production", + "created_by": "admin" + }, + "workflows": [ + { + "name": "logs_to_sumologic", + "handler": { + "name": "sumologic", + "type": "Handler", + "api_version": "core/v2" + } + } + ] + } +] +{{< /code >}} + +{{% notice note %}} +**NOTE**: Read [API response filtering](../../#response-filtering) for more filter statement examples that demonstrate how to filter responses using different operators with label and field selectors. +{{% /notice %}} + +### API Specification + +/pipelines (GET) with response filters | +---------------|------ +description | Returns the list of pipelines that match the [response filters][3] applied in the API request. +example url | http://hostname:8080/api/core/v2/pipelines +pagination | This endpoint supports [pagination][4] using the `limit` and `continue` query parameters. +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "metadata": { + "name": "sensu_email_alerts", + "namespace": "production", + "created_by": "admin" + }, + "workflows": [ + { + "name": "labeled_email_alerts", + "filters": [ + { + "name": "is_incident", + "type": "EventFilter", + "api_version": "core/v2" + }, + { + "name": "state_change_only", + "type": "EventFilter", + "api_version": "core/v2" + } + ], + "mutator": { + "name": "add_labels", + "type": "Mutator", + "api_version": "core/v2" + }, + "handler": { + "name": "email", + "type": "Handler", + "api_version": "core/v2" + } + } + ] + }, + { + "metadata": { + "name": "sensu_to_sumo", + "namespace": "production", + "created_by": "admin" + }, + "workflows": [ + { + "name": "logs_to_sumologic", + "handler": { + "name": "sumologic", + "type": "Handler", + "api_version": "core/v2" + } + } + ] + } +] +{{< /code >}} + + +[1]: ../../../observability-pipeline/observe-process/pipelines/ +[2]: ../../#pagination +[3]: ../../#response-filtering +[4]: https://tools.ietf.org/html/rfc7396 diff --git a/content/sensu-go/6.12/api/core/role-bindings.md b/content/sensu-go/6.12/api/core/role-bindings.md new file mode 100644 index 0000000000..a17276e2c8 --- /dev/null +++ b/content/sensu-go/6.12/api/core/role-bindings.md @@ -0,0 +1,462 @@ +--- +title: "core/v2/rolebindings" +description: "Read this API documentation for information about Sensu's core/v2/rolebindings API endpoints, including examples for retrieving and managing role bindings." +core_api_title: "core/v2/rolebindings" +type: "core_api" +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: core +--- + +{{% notice note %}} +**NOTE**: Requests to `core/v2/rolebindings` API endpoints require you to authenticate with a Sensu [API key](../../#configure-an-environment-variable-for-api-key-authentication) or [access token](../../#authenticate-with-auth-api-endpoints). +The code examples in this document use the [environment variable](../../#configure-an-environment-variable-for-api-key-authentication) `$SENSU_API_KEY` to represent a valid API key in API requests. +{{% /notice %}} + +## Get all role bindings + +The `/rolebindings` API endpoint provides HTTP GET access to [role binding][1] data. + +### Example {#rolebindings-get-example} + +The following example demonstrates a GET request to the `/rolebindings` API endpoint: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/rolebindings \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request results in a successful `HTTP/1.1 200 OK` response and a JSON array that contains the [role binding definitions][1] in the `default` namespace: + +{{< code text >}} +[ + { + "subjects": [ + { + "type": "Group", + "name": "readers" + } + ], + "role_ref": { + "type": "Role", + "name": "read-only" + }, + "metadata": { + "name": "readers-group-binding", + "namespace": "default", + "created_by": "admin" + } + } +] +{{< /code >}} + +### API Specification {#rolebindings-get-specification} + +/rolebindings (GET) | +---------------|------ +description | Returns the list of role bindings. +example url | http://hostname:8080/api/core/v2/namespaces/default/rolebindings +pagination | This endpoint supports [pagination][2] using the `limit` and `continue` query parameters. +response filtering | This endpoint supports [API response filtering][3]. +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "subjects": [ + { + "type": "Group", + "name": "readers" + } + ], + "role_ref": { + "type": "Role", + "name": "read-only" + }, + "metadata": { + "name": "readers-group-binding", + "namespace": "default", + "created_by": "admin" + } + } +] +{{< /code >}} + +## Create a new role binding + +The `/rolebindings` API endpoint provides HTTP POST access to create Sensu role bindings. + +### Example {#rolebindings-post-example} + +In the following example, an HTTP POST request is submitted to the `/rolebindings` API endpoint to create a role binding named `readers-group-binding`: + +{{< code shell >}} +curl -X POST \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "subjects": [ + { + "type": "Group", + "name": "readers" + } + ], + "role_ref": { + "type": "Role", + "name": "read-only" + }, + "metadata": { + "name": "readers-group-binding", + "namespace": "default" + } +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/rolebindings +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#rolebindings-post-specification} + +/rolebindings (POST) | +----------------|------ +description | Creates a Sensu role binding. +example URL | http://hostname:8080/api/core/v2/namespaces/default/rolebindings +payload | {{< code shell >}} +{ + "subjects": [ + { + "type": "Group", + "name": "readers" + } + ], + "role_ref": { + "type": "Role", + "name": "read-only" + }, + "metadata": { + "name": "readers-group-binding", + "namespace": "default" + } +} +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Get a specific role binding {#rolebindingsrolebinding-get} + +The `/rolebindings/:rolebinding` API endpoint provides HTTP GET access to [role binding data][1] for specific `:rolebinding` definitions, by role binding `name`. + +### Example {#rolebindingsrolebinding-get-example} + +The following example queries the `/rolebindings/:rolebinding` API endpoint for the `:rolebinding` named `readers-group-binding`). + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/rolebindings/readers-group-binding \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request will return a successful `HTTP/1.1 200 OK` response and a JSON map that contains the requested [`:rolebinding` definition][1] (in this example, `readers-group-binding`): + +{{< code text >}} +{ + "subjects": [ + { + "type": "Group", + "name": "readers" + } + ], + "role_ref": { + "type": "Role", + "name": "read-only" + }, + "metadata": { + "name": "readers-group-binding", + "namespace": "default", + "created_by": "admin" + } +} +{{< /code >}} + +### API Specification {#rolebindingsrolebinding-get-specification} + +/rolebindings/:rolebinding (GET) | +---------------------|------ +description | Returns the specified role binding. +example url | http://hostname:8080/api/core/v2/namespaces/default/rolebindings/readers-group-binding +response type | Map +response codes |
    • **Success**: 200 (OK)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +{ + "subjects": [ + { + "type": "Group", + "name": "readers" + } + ], + "role_ref": { + "type": "Role", + "name": "read-only" + }, + "metadata": { + "name": "readers-group-binding", + "namespace": "default", + "created_by": "admin" + } +} +{{< /code >}} + +## Create or update a role binding {#rolebindingsrolebinding-put} + +The `/rolebindings/:rolebinding` API endpoint provides HTTP PUT access to create or update [role binding data][1] for specific `:rolebinding` definitions, by role binding `name`. + +### Example {#rolebindingsrolebinding-put-example} + +In the following example, an HTTP PUT request is submitted to the `/rolebindings/:rolebinding` API endpoint to create the role binding `dev-binding`: + +{{< code shell >}} +curl -X PUT \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "subjects": [ + { + "type": "Group", + "name": "devs" + } + ], + "role_ref": { + "type": "Role", + "name": "workflow-creator" + }, + "metadata": { + "name": "dev-binding", + "namespace": "default" + } +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/rolebindings/dev-binding +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#rolebindingsrolebinding-put-specification} + +/rolebindings/:rolebinding (PUT) | +----------------|------ +description | Creates or updates a Sensu role binding. +example URL | http://hostname:8080/api/core/v2/namespaces/default/rolebindings/dev-binding +payload | {{< code shell >}} +{ + "subjects": [ + { + "type": "Group", + "name": "devs" + } + ], + "role_ref": { + "type": "Role", + "name": "workflow-creator" + }, + "metadata": { + "name": "dev-binding", + "namespace": "default" + } +} +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Update a role binding with PATCH + +The `/rolebindings/:rolebinding` API endpoint provides HTTP PATCH access to update `:rolebinding` definitions, specified by role binding name. + +{{% notice note %}} +**NOTE**: You cannot change a resource's `name` or `namespace` with a PATCH request. +Use a [PUT request](#rolebindingsrolebinding-put) instead.

    +Also, you cannot add elements to an array with a PATCH request — you must replace the entire array. +{{% /notice %}} + +### Example + +In the following example, an HTTP PATCH request is submitted to the `/rolebindings/:rolebinding` API endpoint to add a group to the subjects array for the `dev-binding` role binding, resulting in an `HTTP/1.1 200 OK` response and the updated role binding definition. + +We support [JSON merge patches][4], so you must set the `Content-Type` header to `application/merge-patch+json` for PATCH requests. + +{{< code shell >}} +curl -X PATCH \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/merge-patch+json' \ +-d '{ + "subjects": [ + { + "type": "Group", + "name": "dev_team_1" + }, + { + "type": "Group", + "name": "dev_team_2" + } + ] +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/rolebindings/dev-binding +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification + +/rolebindings/:rolebinding (PATCH) | +----------------|------ +description | Updates the specified Sensu role binding. +example URL | http://hostname:8080/api/core/v2/namespaces/default/rolebindings/dev-binding +payload | {{< code shell >}} +{ + "subjects": [ + { + "type": "Group", + "name": "dev_team_1" + }, + { + "type": "Group", + "name": "dev_team_2" + } + ] +} +{{< /code >}} +response codes |
    • **Success**: 200 (OK)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Delete a role binding {#rolebindingsrolebinding-delete} + +The `/rolebindings/:rolebinding` API endpoint provides HTTP DELETE access to delete a role binding from Sensu (specified by the role binding name). + +### Example {#rolebindingsrolebinding-delete-example} + +The following example shows a request to the `/rolebindings/:rolebinding` API endpoint to delete the role binding `dev-binding`, resulting in a successful `HTTP/1.1 204 No Content` response. + +{{< code shell >}} +curl -X DELETE \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/rolebindings/dev-binding \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +### API Specification {#rolebindingsrolebinding-delete-specification} + +/rolebindings/:rolebinding (DELETE) | +--------------------------|------ +description | Removes the specified role binding from Sensu. +example url | http://hostname:8080/api/core/v2/namespaces/default/rolebindings/dev-binding +response codes |
    • **Success**: 204 (No Content)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + +## Get a subset of role bindings with response filtering + +The `/rolebindings` API endpoint supports [response filtering][3] for a subset of role binding data based on labels and the following fields: + +- `rolebinding.name` +- `rolebinding.namespace` +- `rolebinding.role_ref.name` +- `rolebinding.role_ref.type` + +### Example + +The following example demonstrates a request to the `/rolebindings` API endpoint with [response filtering][3] for only [role binding definitions][1] with `event-reader` as the rolebinding.role_ref.name: + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/rolebindings -G \ +--data-urlencode 'fieldSelector="event-reader" in rolebinding.role_ref.name' +{{< /code >}} + +The example request will result in a successful `HTTP/1.1 200 OK` response and a JSON array that contains only [role binding definitions][1] with `event-reader` as the rolebinding.role_ref.name: + +{{< code text >}} +[ + { + "subjects": [ + { + "type": "User", + "name": "ann" + }, + { + "type": "User", + "name": "bonita" + }, + { + "type": "Group", + "name": "admins" + }, + { + "type": "Group", + "name": "read-events" + } + ], + "role_ref": { + "type": "Role", + "name": "event-reader" + }, + "metadata": { + "name": "event-reader-binding", + "namespace": "default", + "labels": { + "sensu.io/managed_by": "sensuctl" + }, + "created_by": "admin" + } + } +] +{{< /code >}} + +{{% notice note %}} +**NOTE**: Read [API response filtering](../../#response-filtering) for more filter statement examples that demonstrate how to filter responses using different operators with label and field selectors. +{{% /notice %}} + +### API Specification + +/rolebindings (GET) with response filters | +---------------|------ +description | Returns the list of role bindings that match the [response filters][3] applied in the API request. +example url | http://hostname:8080/api/core/v2/rolebindings +pagination | This endpoint supports [pagination][2] using the `limit` and `continue` query parameters. +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "subjects": [ + { + "type": "User", + "name": "ann" + }, + { + "type": "User", + "name": "bonita" + }, + { + "type": "Group", + "name": "admins" + }, + { + "type": "Group", + "name": "read-events" + } + ], + "role_ref": { + "type": "Role", + "name": "event-reader" + }, + "metadata": { + "name": "event-reader-binding", + "namespace": "default", + "labels": { + "sensu.io/managed_by": "sensuctl" + }, + "created_by": "admin" + } + } +] +{{< /code >}} + + +[1]: ../../../operations/control-access/rbac/#role-bindings-and-cluster-role-bindings +[2]: ../../#pagination +[3]: ../../#response-filtering +[4]: https://tools.ietf.org/html/rfc7396 diff --git a/content/sensu-go/6.12/api/core/roles.md b/content/sensu-go/6.12/api/core/roles.md new file mode 100644 index 0000000000..94bbcfcb68 --- /dev/null +++ b/content/sensu-go/6.12/api/core/roles.md @@ -0,0 +1,592 @@ +--- +title: "core/v2/roles" +description: "Read this API documentation for information about Sensu core/v2/roles API endpoints, with examples for retrieving and managing Sensu roles." +core_api_title: "core/v2/roles" +type: "core_api" +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: core +--- + +{{% notice note %}} +**NOTE**: Requests to `core/v2/roles` API endpoints require you to authenticate with a Sensu [API key](../../#configure-an-environment-variable-for-api-key-authentication) or [access token](../../#authenticate-with-auth-api-endpoints). +The code examples in this document use the [environment variable](../../#configure-an-environment-variable-for-api-key-authentication) `$SENSU_API_KEY` to represent a valid API key in API requests. +{{% /notice %}} + +## Get all roles + +The `/roles` API endpoint provides HTTP GET access to [role][1] data. + +### Example {#roles-get-example} + +The following example demonstrates a GET request to the `/roles` API endpoint: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/roles \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request results in a successful `HTTP/1.1 200 OK` response and a JSON array that contains the [role definitions][1] in the `default` namespace: + +{{< code text >}} +[ + { + "rules": [ + { + "verbs": [ + "get", + "list" + ], + "resources": [ + "events" + ], + "resource_names": null + } + ], + "metadata": { + "name": "event-reader", + "namespace": "default", + :created_by": "admin" + } + }, + { + "rules": [ + { + "verbs": [ + "get" + ], + "resources": [ + "*" + ], + "resource_names": null + } + ], + "metadata": { + "name": "read-only", + "namespace": "default", + "created_by": "admin" + } + } +] +{{< /code >}} + +### API Specification {#roles-get-specification} + +/roles (GET) | +---------------|------ +description | Returns the list of roles. +example url | http://hostname:8080/api/core/v2/namespaces/default/roles +pagination | This endpoint supports [pagination][2] using the `limit` and `continue` query parameters. +response filtering | This endpoint supports [API response filtering][3]. +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "rules": [ + { + "verbs": [ + "get", + "list" + ], + "resources": [ + "events" + ], + "resource_names": null + } + ], + "metadata": { + "name": "event-reader", + "namespace": "default", + "created_by": "admin" + } + }, + { + "rules": [ + { + "verbs": [ + "get" + ], + "resources": [ + "*" + ], + "resource_names": null + } + ], + "metadata": { + "name": "read-only", + "namespace": "default", + "created_by": "admin" + } + } +] +{{< /code >}} + +## Create a new role + +The `/roles` API endpoint provides HTTP POST access to create Sensu roles. + +### Example {#roles-post-example} + +In the following example, an HTTP POST request is submitted to the `/roles` API endpoint to create a role named `event-reader`: + +{{< code shell >}} +curl -X POST \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "rules": [ + { + "verbs": [ + "get", + "list" + ], + "resources": [ + "events" + ], + "resource_names": [] + } + ], + "metadata": { + "name": "event-reader", + "namespace": "default" + } +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/roles +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#roles-post-specification} + +/roles (POST) | +----------------|------ +description | Creates a Sensu role. +example URL | http://hostname:8080/api/core/v2/namespaces/default/roles +payload | {{< code shell >}} +{ + "rules": [ + { + "verbs": [ + "get", + "list" + ], + "resources": [ + "events" + ], + "resource_names": [] + } + ], + "metadata": { + "name": "event-reader", + "namespace": "default" + } +} +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Get a specific role {#rolesrole-get} + +The `/roles/:role` API endpoint provides HTTP GET access to [role data][1] for specific `:role` definitions, by role name. + +### Example {#rolesrole-get-example} + +The following example queries the `/roles/:role` API endpoint for the `:role` named `read-only`: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/roles/read-only \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request will return a successful `HTTP/1.1 200 OK` response and a JSON map that contains the requested [`:role` definition][1] (in this example, `read-only`): + +{{< code text >}} +{ + "rules": [ + { + "verbs": [ + "read" + ], + "resources": [ + "*" + ], + "resource_names": null + } + ], + "metadata": { + "name": "read-only", + "namespace": "default", + "created_by": "admin" + } +} +{{< /code >}} + +### API Specification {#rolesrole-get-specification} + +/roles/:role (GET) | +---------------------|------ +description | Returns the specified Sensu role. +example url | http://hostname:8080/api/core/v2/namespaces/default/roles/read-only +response type | Map +response codes |
    • **Success**: 200 (OK)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +{ + "rules": [ + { + "verbs": [ + "read" + ], + "resources": [ + "*" + ], + "resource_names": null + } + ], + "metadata": { + "name": "read-only", + "namespace": "default", + "created_by": "admin" + } +} +{{< /code >}} + +## Create or update a role {#rolesrole-put} + +The `/roles/:role` API endpoint provides HTTP PUT access to create or update specific `:role` definitions, by role name. + +### Example {#rolesrole-put-example} + +In the following example, an HTTP PUT request is submitted to the `/roles/:role` API endpoint to create the role `read-only`: + +{{< code shell >}} +curl -X PUT \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "rules": [ + { + "verbs": [ + "read" + ], + "resources": [ + "*" + ], + "resource_names": null + } + ], + "metadata": { + "name": "read-only", + "namespace": "default" + } +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/roles/read-only +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#rolesrole-put-specification} + +/roles/:role (PUT) | +----------------|------ +description | Creates or updates the specified Sensu role. +example URL | http://hostname:8080/api/core/v2/namespaces/default/roles/event-reader +payload | {{< code shell >}} +{ + "rules": [ + { + "verbs": [ + "read" + ], + "resources": [ + "*" + ], + "resource_names": null + } + ], + "metadata": { + "name": "read-only", + "namespace": "default" + } +} +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Update a role with PATCH + +The `/roles/:role` API endpoint provides HTTP PATCH access to update `:role` definitions, specified by role name. + +{{% notice note %}} +**NOTE**: You cannot change a resource's `name` or `namespace` with a PATCH request. +Use a [PUT request](#rolesrole-put) instead.

    +Also, you cannot add elements to an array with a PATCH request — you must replace the entire array. +{{% /notice %}} + +### Example + +In the following example, an HTTP PATCH request is submitted to the `/roles/:role` API endpoint to update the verbs array within the rules array for the `global-event-admin` role, resulting in an `HTTP/1.1 200 OK` response and the updated role definition. + +We support [JSON merge patches][4], so you must set the `Content-Type` header to `application/merge-patch+json` for PATCH requests. + +{{< code shell >}} +curl -X PATCH \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/merge-patch+json' \ +-d '{ + "rules": [ + { + "verbs": [ + "get", + "list" + ], + "resources": [ + "events" + ], + "resource_names": null + } + ] +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/roles/event-reader +{{< /code >}} + +### API Specification + +/roles/:role (PATCH) | +----------------|------ +description | Updates the specified Sensu role. +example URL | http://hostname:8080/api/core/v2/namespaces/default/roles/event-reader +payload | {{< code shell >}} +{ + "rules": [ + { + "verbs": [ + "get", + "list" + ], + "resources": [ + "events" + ], + "resource_names": null + } + ] +} +{{< /code >}} +response codes |
    • **Success**: 200 (OK)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Delete a role {#rolesrole-delete} + +The `/roles/:role` API endpoint provides HTTP DELETE access to delete a role from Sensu (specified by the role name). + +### Example {#rolesrole-delete-example} + +The following example shows a request to the `/roles/:role` API endpoint to delete the role `read-only`, resulting in a successful `HTTP/1.1 204 No Content` response: + +{{< code shell >}} +curl -X DELETE \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/roles/read-only \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +### API Specification {#rolesrole-delete-specification} + +/roles/:role (DELETE) | +--------------------------|------ +description | Removes the specified role from Sensu. +example url | http://hostname:8080/api/core/v2/namespaces/default/roles/read-only +response codes |
    • **Success**: 204 (No Content)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + +## Get a subset of roles with response filtering + +The `/roles` API endpoint supports [response filtering][3] for a subset of role data based on labels and the following fields: + +- `role.name` +- `role.namespace` + +### Example + +The following example demonstrates a request to the `/roles` API endpoint with [response filtering][3] for only [role definitions][1] that are in the `development` namespace: + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/roles -G \ +--data-urlencode 'fieldSelector=role.namespace == development' +{{< /code >}} + +The example request will result in a successful `HTTP/1.1 200 OK` response and a JSON array that contains only [role definitions][1] in the `development` namespace: + +{{< code text >}} +[ + { + "rules": [ + { + "verbs": [ + "get", + "list", + "create", + "update", + "delete" + ], + "resources": [ + "*" + ], + "resource_names": null + } + ], + "metadata": { + "name": "admin_role", + "namespace": "development", + "created_by": "admin" + } + }, + { + "rules": [ + { + "verbs": [ + "get", + "list", + "create", + "update", + "delete" + ], + "resources": [ + "assets", + "checks", + "entities", + "events", + "filters", + "handlers", + "hooks", + "mutators", + "pipelines", + "rolebindings", + "roles", + "silenced" + ], + "resource_names": null + } + ], + "metadata": { + "name": "namespaced-resources-all-verbs", + "namespace": "development", + "created_by": "admin" + } + }, + { + "rules": [ + { + "verbs": [ + "get", + "list" + ], + "resources": [ + "events" + ], + "resource_names": null + } + ], + "metadata": { + "name": "system:pipeline", + "namespace": "development" + } + } +] +{{< /code >}} + +{{% notice note %}} +**NOTE**: Read [API response filtering](../../#response-filtering) for more filter statement examples that demonstrate how to filter responses using different operators with label and field selectors. +{{% /notice %}} + +### API Specification + +/roles (GET) with response filters | +---------------|------ +description | Returns the list of roles that match the [response filters][3] applied in the API request. +example url | http://hostname:8080/api/core/v2/roles +pagination | This endpoint supports [pagination][2] using the `limit` and `continue` query parameters. +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "rules": [ + { + "verbs": [ + "get", + "list", + "create", + "update", + "delete" + ], + "resources": [ + "*" + ], + "resource_names": null + } + ], + "metadata": { + "name": "admin_role", + "namespace": "development", + "created_by": "admin" + } + }, + { + "rules": [ + { + "verbs": [ + "get", + "list", + "create", + "update", + "delete" + ], + "resources": [ + "assets", + "checks", + "entities", + "events", + "filters", + "handlers", + "hooks", + "mutators", + "pipelines", + "rolebindings", + "roles", + "silenced" + ], + "resource_names": null + } + ], + "metadata": { + "name": "namespaced-resources-all-verbs", + "namespace": "development", + "created_by": "admin" + } + }, + { + "rules": [ + { + "verbs": [ + "get", + "list" + ], + "resources": [ + "events" + ], + "resource_names": null + } + ], + "metadata": { + "name": "system:pipeline", + "namespace": "development" + } + } +] +{{< /code >}} + + +[1]: ../../../operations/control-access/rbac/#roles-and-cluster-roles +[2]: ../../#pagination +[3]: ../../#response-filtering +[4]: https://tools.ietf.org/html/rfc7396 diff --git a/content/sensu-go/6.12/api/core/silenced.md b/content/sensu-go/6.12/api/core/silenced.md new file mode 100644 index 0000000000..4e6386331e --- /dev/null +++ b/content/sensu-go/6.12/api/core/silenced.md @@ -0,0 +1,530 @@ +--- +title: "core/v2/silenced" +description: "Read this API documentation for information about Sensu core/v2/silenced API endpoints, with examples for retrieving and managing silences." +core_api_title: "core/v2/silenced" +type: "core_api" +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: core +--- + +{{% notice note %}} +**NOTE**: Requests to `core/v2/silenced` API endpoints require you to authenticate with a Sensu [API key](../../#configure-an-environment-variable-for-api-key-authentication) or [access token](../../#authenticate-with-auth-api-endpoints). +The code examples in this document use the [environment variable](../../#configure-an-environment-variable-for-api-key-authentication) `$SENSU_API_KEY` to represent a valid API key in API requests. +{{% /notice %}} + +## Get all silences + +The `/silenced` API endpoint provides HTTP GET access to [silencing entry][1] data. + +### Example {#silenced-get-example} + +The following example demonstrates a GET request to the `/silenced` API endpoint: + +{{< code shell >}} +curl -X GET \ +-H "Authorization: Key $SENSU_API_KEY" \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/silenced +{{< /code >}} + +The request results in a successful `HTTP/1.1 200 OK` response and a JSON array that contains the [silencing definitions][1] in the `default` namespace: + +{{< code text >}} +[ + { + "metadata": { + "name": "*:http", + "namespace": "default", + "created_by": "admin" + }, + "expire": -1, + "expire_on_resolve": false, + "creator": "admin", + "check": "http", + "reason": "Testing", + "begin": 1605024595, + "expire_at": 0 + }, + { + "metadata": { + "name": "linux:*", + "namespace": "default", + "created_by": "admin" + }, + "expire": -1, + "expire_on_resolve": false, + "creator": "admin", + "reason": "reason for silence", + "subscription": "linux", + "begin": 1542671205, + "expire_at": 0 + } +] +{{< /code >}} + +### API Specification {#silenced-get-specification} + +/silenced (GET) | +---------------|------ +description | Returns the list of silences. +example url | http://hostname:8080/api/core/v2/namespaces/default/silenced +pagination | This endpoint does not support [pagination][2]. +response filtering | This endpoint supports [API response filtering][3]. +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "metadata": { + "name": "*:http", + "namespace": "default", + "created_by": "admin" + }, + "expire": -1, + "expire_on_resolve": false, + "creator": "admin", + "check": "http", + "reason": "Testing", + "begin": 1605024595, + "expire_at": 0 + }, + { + "metadata": { + "name": "linux:*", + "namespace": "default", + "created_by": "admin" + }, + "expire": -1, + "expire_on_resolve": false, + "creator": "admin", + "reason": "reason for silence", + "subscription": "linux", + "begin": 1542671205, + "expire_at": 0 + } +] +{{< /code >}} + +## Create a new silence + +The `/silenced` API endpoint provides HTTP POST access to create silencing entries. + +### Example {#silenced-post-example} + +In the following example, an HTTP POST request is submitted to the `/silenced` API endpoint to create the silencing entry `linux:check_cpu`: + +{{< code shell >}} +curl -X POST \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "metadata": { + "name": "linux:check_cpu", + "namespace": "default", + "labels": null, + "annotations": null + }, + "expire": -1, + "expire_on_resolve": false, + "creator": "admin", + "reason": "reason for silence", + "subscription": "linux", + "begin": 1542671205 +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/silenced +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +Here's another example that shows an HTTP POST request to the `/silenced` API endpoint to create the silencing entry `*:http`, which will create a silence for any event with the check name `http`, regardless of the originating entities’ subscriptions: + +{{< code shell >}} +curl -X POST \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "metadata": { + "name": "*:http", + "namespace": "default", + "labels": null, + "annotations": null + }, + "expire": -1, + "expire_on_resolve": false, + "creator": "admin", + "check": "http", + "reason": "Testing" +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/silenced +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#silenced-post-specification} + +/silenced (POST) | +----------------|------ +description | Creates a Sensu silencing entry. +example URL | http://hostname:8080/api/core/v2/namespaces/default/silenced +payload | {{< code shell >}} +{ + "metadata": { + "name": "linux:check_cpu", + "namespace": "default", + "labels": null, + "annotations": null + }, + "expire": -1, + "expire_on_resolve": false, + "creator": "admin", + "reason": "reason for silence", + "subscription": "linux", + "begin": 1542671205 +} +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Get a specific silence {#silencedsilenced-get} + +The `/silenced/:silenced` API endpoint provides HTTP GET access to [silencing entry data][1] for specific `:silenced` definitions, by silencing entry name. + +### Example {#silencedsilenced-get-example} + +The following example queries the `/silenced/:silenced` API endpoint for the silencing entry named `linux:check_cpu`: + +{{< code shell >}} +curl -X GET \ +-H "Authorization: Key $SENSU_API_KEY" \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/silenced/linux:check_cpu +{{< /code >}} + +The request will return a successful `HTTP/1.1 200 OK` response and a JSON map that contains the requested [`:silenced` definition][1] (in this example, `linux:check_cpu`): + +{{< code text >}} +{ + "metadata": { + "name": "linux:check_cpu", + "namespace": "default", + "created_by": "admin", + "labels": null, + "annotations": null + }, + "expire": -1, + "expire_on_resolve": false, + "creator": "admin", + "reason": "reason for silence", + "subscription": "linux", + "begin": 1542671205 +} +{{< /code >}} + +### API Specification {#silencedsilenced-get-specification} + +/silenced/:silenced (GET) | +---------------------|------ +description | Returns the specified silencing entry. +example url | http://hostname:8080/api/core/v2/namespaces/default/silenced/linux:check_cpu +response type | Map +response codes |
    • **Success**: 200 (OK)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +{ + "metadata": { + "name": "linux:check_cpu", + "namespace": "default", + "created_by": "admin", + "labels": null, + "annotations": null + }, + "expire": -1, + "expire_on_resolve": false, + "creator": "admin", + "reason": "reason for silence", + "subscription": "linux", + "begin": 1542671205 +} +{{< /code >}} + +## Create or update a silence {#silencedsilenced-put} + +The `/silenced/:silenced` API endpoint provides HTTP PUT access to create or update specific `:silenced` definitions, by silencing entry name. + +### Example {#silencedsilenced-put-example} + +In the following example, an HTTP PUT request is submitted to the `/silenced/:silenced` API endpoint to create the silencing entry `linux:check-server`: + +{{< code shell >}} +curl -X PUT \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "metadata": { + "name": "linux:check-server", + "namespace": "default", + "labels": null, + "annotations": null + }, + "expire": -1, + "expire_on_resolve": false, + "creator": "admin", + "reason": "reason for silence", + "subscription": "linux", + "begin": 1542671205 +}' \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/silenced/linux:check-server +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#silencedsilenced-put-specification} + +/silenced/:silenced (PUT) | +----------------|------ +description | Creates or updates a Sensu silencing entry. +example URL | http://hostname:8080/api/core/v2/namespaces/default/silenced/linux:check-server +payload | {{< code shell >}} +{ + "metadata": { + "name": "linux:check-server", + "namespace": "default", + "labels": null, + "annotations": null + }, + "expire": -1, + "expire_on_resolve": false, + "creator": "admin", + "reason": "reason for silence", + "subscription": "linux", + "begin": 1542671205 +} +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Delete a silence {#silencedsilenced-delete} + +The `/silenced/:silenced` API endpoint provides HTTP DELETE access to delete a silencing entry (specified by the silencing entry name). + +### Example {#silencedsilenced-delete-example} + +In the following example, querying the `/silenced/:silenced` API endpoint to delete the the silencing entry named `linux:check_cpu` results in a successful `HTTP/1.1 204 No Content` response: + +{{< code shell >}} +curl -X DELETE \ +-H "Authorization: Key $SENSU_API_KEY" \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/silenced/linux:check_cpu +{{< /code >}} + +### API Specification {#silencedsilenced-delete-specification} + +/silenced/:silenced (DELETE) | +--------------------------|------ +description | Removes the specified silencing entry from Sensu. +example url | http://hostname:8080/api/core/v2/namespaces/default/silenced/linux:check_cpu +response codes |
    • **Success**: 204 (No Content)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + +## Get all silences for a specific subscription {#silencedsubscriptions-get} + +The `/silenced/subscriptions/:subscription` API endpoint provides HTTP GET access to [silencing entry data][1] by subscription name. + +### Example {#silencedsubscriptions-get-example} + +The following example queries the `silenced/subscriptions/:subscription` API endpoint for [silences][1] for the given subscription (in this example, for the `linux` subscription): + +{{< code shell >}} +curl -X GET \ +-H "Authorization: Key $SENSU_API_KEY" \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/silenced/subscriptions/linux +{{< /code >}} + +The example request will result in a successful `HTTP/1.1 200 OK` response and a JSON array that contains only [silencing definitions][1] for the `linux` subscription: + +{{< code text >}} +[ + { + "metadata": { + "name": "linux:check_cpu", + "namespace": "default", + "created_by": "admin", + "labels": null, + "annotations": null + }, + "expire": -1, + "expire_on_resolve": false, + "creator": "admin", + "reason": "reason for silence", + "subscription": "linux", + "begin": 1542671205 + } +] +{{< /code >}} + +### API Specification {#silencedsubscriptions-get-specification} + +/silenced/subscriptions/:subscription (GET) | +---------------------|------ +description | Returns all silences for the specified subscription. +example url | http://hostname:8080/api/core/v2/namespaces/default/silenced/subscriptions/linux +pagination | This endpoint supports [pagination][2] using the `limit` and `continue` query parameters. +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "metadata": { + "name": "linux:check_cpu", + "namespace": "default", + "created_by": "admin", + "labels": null, + "annotations": null + }, + "expire": -1, + "expire_on_resolve": false, + "creator": "admin", + "reason": "reason for silence", + "subscription": "linux", + "begin": 1542671205 + } +] +{{< /code >}} + +## Get all silences for a specific check {#silencedchecks-get} + +The `/silenced/checks/:check` API endpoint provides HTTP GET access to [silencing entry data][1] by check name. + +### Example {#silencedchecks-get-example} + +The following example queries the `silenced/checks/:check` API endpoint for [silences][1] for the specified check (in this example, for the `check_cpu` check): + +{{< code shell >}} +curl -X GET \ +-H "Authorization: Key $SENSU_API_KEY" \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/silenced/checks/check_cpu +{{< /code >}} + +The example request will result in a successful `HTTP/1.1 200 OK` response and a JSON array that contains only [silencing definitions][1] for the `check_cpu` check: + +{{< code text >}} +[ + { + "metadata": { + "name": "linux:check_cpu", + "namespace": "default", + "created_by": "admin", + "labels": null, + "annotations": null + }, + "expire": -1, + "expire_on_resolve": false, + "creator": "admin", + "reason": "reason for silence", + "check": "linux", + "begin": 1542671205 + } +] +{{< /code >}} + +### API Specification {#silencedchecks-get-specification} + +/silenced/checks/:check (GET) | +---------------------|------ +description | Returns all silences for the specified check. +example url | http://hostname:8080/api/core/v2/namespaces/default/silenced/checks/check_cpu +pagination | This endpoint supports [pagination][2] using the `limit` and `continue` query parameters. +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "metadata": { + "name": "linux:check_cpu", + "namespace": "default", + "created_by": "admin", + "labels": null, + "annotations": null + }, + "expire": -1, + "expire_on_resolve": false, + "creator": "admin", + "reason": "reason for silence", + "check": "linux", + "begin": 1542671205 + } +] +{{< /code >}} + +## Get a subset of silences with response filtering + +The `/silenced` API endpoint supports [response filtering][3] for a subset of silences data based on labels and the following fields: + +- `silenced.name` +- `silenced.namespace` +- `silenced.check` +- `silenced.creator` +- `silenced.expire_on_resolve` +- `silenced.subscription` + +### Example + +The following example demonstrates a request to the `/silenced` API endpoint with [response filtering][3] for only [silencing definitions][1] in the `development` namespace: + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/silenced -G \ +--data-urlencode 'fieldSelector="development" in silenced.namespace' +{{< /code >}} + +The example request will result in a successful `HTTP/1.1 200 OK` response and a JSON array that contains only [silencing definitions][1] in the `development` namespace: + +{{< code text >}} +[ + { + "metadata": { + "name": "linux:*", + "namespace": "development", + "created_by": "admin" + }, + "expire": -1, + "expire_on_resolve": false, + "creator": "admin", + "subscription": "linux", + "begin": 1644868317, + "expire_at": 0 + } +] +{{< /code >}} + +{{% notice note %}} +**NOTE**: Read [API response filtering](../../#response-filtering) for more filter statement examples that demonstrate how to filter responses using different operators with label and field selectors. +{{% /notice %}} + +### API Specification + +/silenced (GET) with response filters | +---------------|------ +description | Returns the list of silences that match the [response filters][3] applied in the API request. +example url | http://hostname:8080/api/core/v2/silenced +pagination | This endpoint supports [pagination][2] using the `limit` and `continue` query parameters. +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "metadata": { + "name": "linux:*", + "namespace": "development", + "created_by": "admin" + }, + "expire": -1, + "expire_on_resolve": false, + "creator": "admin", + "subscription": "linux", + "begin": 1644868317, + "expire_at": 0 + } +] +{{< /code >}} + + +[1]: ../../../observability-pipeline/observe-process/silencing/ +[2]: ../../#pagination +[3]: ../../#response-filtering diff --git a/content/sensu-go/6.12/api/core/tessen.md b/content/sensu-go/6.12/api/core/tessen.md new file mode 100644 index 0000000000..5ad6aef873 --- /dev/null +++ b/content/sensu-go/6.12/api/core/tessen.md @@ -0,0 +1,105 @@ +--- +title: "core/v2/tessen" +description: "Read this API documentation for information about Sensu core/v2/tessen API endpoints, which provide HTTP access to manage Tessen configuration." +core_api_title: "core/v2/tessen" +type: "core_api" +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: core +--- + +{{% notice note %}} +**NOTE**: Requests to `core/v2/tessen` API endpoints require you to authenticate with a Sensu [API key](../../#configure-an-environment-variable-for-api-key-authentication) or [access token](../../#authenticate-with-auth-api-endpoints). +The code examples in this document use the [environment variable](../../#configure-an-environment-variable-for-api-key-authentication) `$SENSU_API_KEY` to represent a valid API key in API requests. +{{% /notice %}} + +The core/v2/tessen API endpoints provide HTTP access to manage [Tessen][1] configuration. +Access to core/v2/tessen is restricted to the default [`admin` user][2]. + +## Get the active Tessen configuration {#tessen-get} + +The `/tessen` API endpoint provides HTTP GET access to the active Tessen configuration. + +### Example {#tessen-get-example} + +The following example demonstrates an HTTP GET request to the `/tessen` API endpoint: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/core/v2/tessen \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request returns an HTTP `200 OK` response and a JSON map that contains the active Tessen configuration, indicating whether Tessen is enabled: + +{{< code text >}} +{ + "opt_out": false +} +{{< /code >}} + +### API Specification {#tessen-get-specification} + +/tessen (GET) | +---------------|------ +description | Returns the active Tessen configuration. An `"opt_out": false` response indicates that Tessen is enabled. An `"opt_out": true` response indicates that Tessen is disabled. +example url | http://hostname:8080/api/core/v2/tessen +response type | Map +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +example output | {{< code text >}} +{ + "opt_out": false +} +{{< /code >}} + +## Opt in to or out of Tessen {#tessen-put} + +The `/tessen` API endpoint provides HTTP PUT access to opt in to or opt out of Tessen for unlicensed Sensu instances. + +{{% notice note %}} +**NOTE**: Tessen is enabled by default on Sensu backends and required for [licensed](../../../operations/maintain-sensu/license) Sensu instances. +If you have a licensed instance and want to opt out of Tessen, contact your account manager. +{{% /notice %}} + +### Example {#tessen-put-example} + +In the following example, an HTTP PUT request is submitted to the `/tessen` API endpoint to opt in to Tessen using the `opt_out` attribute: + +{{< code shell >}} +curl -X PUT \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "opt_out": false +}' \ +http://127.0.0.1:8080/api/core/v2/tessen +{{< /code >}} + +The request returns an HTTP `200 OK` response and the resulting Tessen configuration. + +{{< code text >}} +{ + "opt_out": false +} +{{< /code >}} + +### API Specification {#tessen-put-specification} + +/tessen (PUT) | +----------------|------ +description | Updates the active Tessen configuration for unlicensed Sensu instances. Tessen is enabled by default on Sensu backends and required for [licensed][3] Sensu instances. +example url | http://hostname:8080/api/core/v2/tessen +request parameters | Required: `opt_out` (for unlicensed instances, set to `false` to enable Tessen; set to `true` to opt out of Tessen). +response codes |
    • **Success**: 200 (OK)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    +example output | {{< code text >}} +{ + "opt_out": false +} +{{< /code >}} + + +[1]: ../../../operations/monitor-sensu/tessen/ +[2]: ../../../operations/control-access/rbac#default-users +[3]: ../../../operations/maintain-sensu/license diff --git a/content/sensu-go/6.12/api/core/users.md b/content/sensu-go/6.12/api/core/users.md new file mode 100644 index 0000000000..1a00a86edc --- /dev/null +++ b/content/sensu-go/6.12/api/core/users.md @@ -0,0 +1,512 @@ +--- +title: "core/v2/users" +description: "Read this API documentation for details about Sensu core/v2/users API endpoints, with examples for creating and managing Sensu user data to match your workflow." +core_api_title: "core/v2/users" +type: "core_api" +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: core +--- + +{{% notice note %}} +**NOTE**: The `core/v2/users` API endpoints allow you to create and manage user credentials with Sensu's built-in [basic authentication](../../../operations/control-access#use-built-in-basic-authentication). +To configure user credentials with an external provider like [Lightweight Directory Access Protocol (LDAP)](../../../operations/control-access/ldap-auth/), [Active Directory (AD)](../../../operations/control-access/ad-auth/), or [OpenID Connect 1.0 protocol (OIDC)](../../../operations/control-access/oidc-auth/), use Sensu's [enterprise/authentication/v2 API endpoints](../../enterprise/authproviders/).

    +Requests to `core/v2/users` API endpoints require you to authenticate with a Sensu [API key](../../#configure-an-environment-variable-for-api-key-authentication) or [access token](../../#authenticate-with-auth-api-endpoints). +The code examples in this document use the [environment variable](../../#configure-an-environment-variable-for-api-key-authentication) `$SENSU_API_KEY` to represent a valid API key in API requests. +{{% /notice %}} + +## Get all users + +The `/users` API endpoint provides HTTP GET access to [user][1] data. + +### Example {#users-get-example} + +The following example demonstrates a GET request to the `/users` API: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/core/v2/users \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request results in a successful `HTTP/1.1 200 OK` response and a JSON array that contains all [user definitions][1]: + +{{< code text >}} +[ + { + "username": "admin", + "groups": [ + "cluster-admins" + ], + "disabled": false + }, + { + "username": "agent", + "groups": [ + "system:agents" + ], + "disabled": false + } +] +{{< /code >}} + +### API Specification {#users-get-specification} + +/users (GET) | +---------------|------ +description | Returns the list of users. +example url | http://hostname:8080/api/core/v2/users +pagination | This endpoint supports [pagination][2] using the `limit` and `continue` query parameters. +response filtering | This endpoint supports [API response filtering][8]. +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "username": "admin", + "groups": [ + "cluster-admins" + ], + "disabled": false + }, + { + "username": "agent", + "groups": [ + "system:agents" + ], + "disabled": false + } +] +{{< /code >}} + +## Create a new user + +The `/users` API endpoint provides HTTP POST access to create a [user][1] using Sensu's basic authentication provider. + +### Example {#users-post-example} + +The following example demonstrates a POST request to the `/users` API endpoint to create the user `alice`: + +{{< code shell >}} +curl -X POST \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "username": "alice", + "groups": [ + "ops" + ], + "password": "temporary", + "disabled": false +}' \ +http://127.0.0.1:8080/api/core/v2/users +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#usersuser-post-specification} + +/users (POST) | +----------------|------ +description | Creates a Sensu user. +example URL | http://hostname:8080/api/core/v2/users +payload parameters | Required: `username` (string), `groups` (array; sets of shared permissions that apply to this user), `password` (string; at least eight characters), and `disabled` (when set to `true`, invalidates user credentials and permissions). +payload | {{< code shell >}} +{ + "username": "alice", + "groups": [ + "ops" + ], + "password": "temporary", + "disabled": false +} +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Get a specific user {#usersuser-get} + +The `/users/:user` API endpoint provides HTTP GET access to [user data][1] for a specific user by `username`. + +### Example {#usersuser-get-example} + +The following example queries the `/users/:user` API for the `alice` user: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/core/v2/users/alice \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request will return a successful `HTTP/1.1 200 OK` response and a JSON map that contains the requested [`:user` definition][1] (in this example, `alice`): + +{{< code text >}} +{ + "username": "alice", + "groups": [ + "ops" + ], + "disabled": false +} +{{< /code >}} + +### API Specification {#usersuser-get-specification} + +/users/:user (GET) | +---------------------|------ +description | Returns the specified user. +example url | http://hostname:8080/api/core/v2/users/alice +response type | Map +response codes |
    • **Success**: 200 (OK)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +{ + "username": "alice", + "groups": [ + "ops" + ], + "disabled": false +} +{{< /code >}} + +## Create or update a user {#usersuser-put} + +The `/users/:user` API endpoint provides HTTP PUT access to create or update [user data][1] for a specific user by `username`. + +{{% notice note %}} +**NOTE**: Use the [`PUT /users/:user/reset_password`](#usersuserresetpassword-put) or [`PUT /users/:user/password`](#usersuserpassword-put) API endpoints to reset or change the user password, respectively. +{{% /notice %}} + +### Example {#users-put-example} + +The following example demonstrates a PUT request to the `/users` API endpoint to update the user `alice` (for example, to add the user to the `devel` group): + +{{< code shell >}} +curl -X PUT \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "username": "alice", + "groups": [ + "ops", + "devel" + ], + "password": "password", + "disabled": false +}' \ +http://127.0.0.1:8080/api/core/v2/users/alice +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#usersuser-put-specification} + +/users/:user (PUT) | +----------------|------ +description | Creates or updates user data for the specified Sensu user. +example URL | http://hostname:8080/api/core/v2/users/alice +payload | {{< code shell >}} +{ + "username": "alice", + "groups": [ + "ops", + "devel" + ], + "password": "password", + "disabled": false +} +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Disable a user {#usersuser-delete} + +The `/users/:user` API endpoint provides HTTP DELETE access to disable a specific user by `username`. + +### Example {#usersuser-delete-example} + +In the following example, an HTTP DELETE request is submitted to the `/users/:user` API endpoint to disable the user `alice`, resulting in a successful `HTTP/1.1 204 No Content` response. + +{{< code shell >}} +curl -X DELETE \ +-H "Authorization: Key $SENSU_API_KEY" \ +http://127.0.0.1:8080/api/core/v2/users/alice +{{< /code >}} + +{{% notice note %}} +**NOTE**: This endpoint **disables** but does not delete the user. +You can [reinstate](#usersuserreinstate-put) disabled users. +{{% /notice %}} + +### API Specification {#usersuser-delete-specification} + +/users/:user (DELETE) | +--------------------------|------ +description | Disables the specified user. +example url | http://hostname:8080/api/core/v2/users/alice +response codes |
    • **Success**: 204 (No Content)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + +## Reset a user's password {#usersuserresetpassword-put} + +The `/users/:user/reset_password` API endpoint provides HTTP PUT access to reset a user's password. + +{{% notice note %}} +**NOTE**: The `/users/:user/reset_password` API endpoint requires explicit [`users` permissions](../../../operations/control-access/rbac/#users). +With these permissions, you can use `/users/:user/reset_password` to reset a user's password. +This differs from the `/users/:user/password` API endpoint, which allows users to change their own passwords without explicit permissions. +{{% /notice %}} + +### Example {#usersuserresetpassword-put-example} + +In the following example, an HTTP PUT request is submitted to the `/users/:user/reset_password` API endpoint to reset the password for the user `alice`. + +The `password_hash` is the user's new password, hashed via [bcrypt][3]. +Use `sensuctl user hash-password` to [generate the `password_hash`][4]. + +{{< code shell >}} +curl -X PUT \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "username": "alice", + "password_hash": "$5f$14$.brXRviMZpbaleSq9kjoUuwm67V/s4IziOLGHjEqxJbzPsreQAyNm" +}' \ +http://127.0.0.1:8080/api/core/v2/users/alice/reset_password +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#usersuserresetpassword-put-specification} + +/users/:user/reset_password (PUT) | +----------------|------ +description | Resets the password for the specified Sensu user. +example URL | http://hostname:8080/api/core/v2/users/alice/reset_password +payload parameters | Required:
    • `username`: string; the username for the Sensu user
    • `password_hash`: string; the new user password, hashed via [bcrypt][3]
    +payload | {{< code shell >}} +{ + "username": "alice", + "password_hash": "$5f$14$.brXRviMZpbaleSq9kjoUuwm67V/s4IziOLGHjEqxJbzPsreQAyNm" +} +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Change your password {#usersuserpassword-put} + +The `/users/:user/password` API endpoint provides HTTP PUT access to change your Sensu user password. + +{{% notice note %}} +**NOTE**: The `/users/:user/password` API endpoint allows a user to update their own password, without any permissions. +This differs from the `/users/:user/reset_password` API endpoint, which requires explicit [`users` permissions](../../../operations/control-access/rbac/#users) to change the user password. +{{% /notice %}} + +### Example {#usersuserpassword-put-example} + +In the following example, an HTTP PUT request is submitted to the `/users/:user/password` API endpoint to update the password for the user `alice`. + +The `password` is your current password in cleartext. +The `password_hash` is your new password hashed via [bcrypt][3]. +Use `sensuctl user hash-password` to [generate the `password_hash`][4]. + +{{< code shell >}} +curl -X PUT \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "username": "alice", + "password": "P@ssw0rd!", + "password_hash": "$5f$14$.brXRviMZpbaleSq9kjoUuwm67V/s4IziOLGHjEqxJbzPsreQAyNm" +}' \ +http://127.0.0.1:8080/api/core/v2/users/alice/password +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#usersuserpassword-put-specification} + +/users/:user/password (PUT) | +----------------|------ +description | Changes the password for the specified Sensu user. +example URL | http://hostname:8080/api/core/v2/users/alice/password +payload parameters | Required:
    • `username`: string; the username for the Sensu user
    • `password`: string; the user's current password in cleartext
    • `password_hash`: string; the user's hashed password via [bcrypt][3]
    +payload | {{< code shell >}} +{ + "username": "alice", + "password": "P@ssw0rd!", + "password_hash": "$5f$14$.brXRviMZpbaleSq9kjoUuwm67V/s4IziOLGHjEqxJbzPsreQAyNm" +} +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Reinstate a disabled user {#usersuserreinstate-put} + +The `/users/:user/reinstate` API endpoint provides HTTP PUT access to reinstate a disabled user. + +### Example {#usersuserreinstate-put-example} + +In the following example, an HTTP PUT request is submitted to the `/users/:user/reinstate` API endpoint to reinstate the disabled user `alice`: + +{{< code shell >}} +curl -X PUT \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +http://127.0.0.1:8080/api/core/v2/users/alice/reinstate +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#usersuserreinstate-put-specification} + +/users/:user/reinstate (PUT) | +----------------|------ +description | Reinstates a disabled user. +example URL | http://hostname:8080/api/core/v2/users/alice/reinstate +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Remove a user from all groups {#usersusergroups-delete} + +The `/users/:user/groups` API endpoint provides HTTP DELETE access to remove the specified user from all groups. + +### Example {#usersusergroups-delete-example} + +In the following example, an HTTP DELETE request is submitted to the `/users/:user/groups` API endpoint to remove the user `alice` from all groups within Sensu, resulting in a successful `HTTP/1.1 204 No Content` response: + +{{< code shell >}} +curl -X DELETE \ +-H "Authorization: Key $SENSU_API_KEY" \ +http://127.0.0.1:8080/api/core/v2/users/alice/groups +{{< /code >}} + +### API Specification {#usersusergroups-delete-specification} + +/users/:user/groups (DELETE) | +--------------------------|------ +description | Removes the specified user from all groups. +example url | http://hostname:8080/api/core/v2/users/alice/groups +response codes |
    • **Success**: 204 (No Content)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + +## Assign a user to a group {#usersusergroupsgroup-put} + +The `/users/:user/groups/:group` API endpoint provides HTTP PUT access to assign a user to a group. + +### Example {#usersusergroupsgroup-put-example} + +In the following example, an HTTP PUT request is submitted to the `/users/:user/groups/:group` API endpoint to add the user `alice` to the group `ops`: + +{{< code shell >}} +curl -X PUT \ +-H "Authorization: Key $SENSU_API_KEY" \ +http://127.0.0.1:8080/api/core/v2/users/alice/groups/ops +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#usersusergroupsgroup-put-specification} + +/users/:user/groups/:group (PUT) | +----------------|------ +description | Adds the specified user to the specified group. +example URL | http://hostname:8080/api/core/v2/users/alice/groups/ops +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Remove a user from a specific group {#usersusergroupsgroup-delete} + +The `/users/:user/groups/:group` API endpoint provides HTTP DELETE access to remove the specified user from a specific group. + +### Example {#usersusergroupsgroup-delete-example} + +In the following example, an HTTP DELETE request is submitted to the `/users/:user/groups/:group` API endpoint to remove the user `alice` from the group `ops`, resulting in a successful `HTTP/1.1 204 No Content` response: + +{{< code shell >}} +curl -X DELETE \ +-H "Authorization: Key $SENSU_API_KEY" \ +http://127.0.0.1:8080/api/core/v2/users/alice/groups/ops +{{< /code >}} + +### API Specification {#usersusergroupsgroup-delete-specification} + +/users/:user/groups/:group (DELETE) | +--------------------------|------ +description | Removes the specified user from the specified group. +example url | http://hostname:8080/api/core/v2/users/alice/groups/ops +response codes |
    • **Success**: 204 (No Content)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + +## Get a subset of users with response filtering + +The `/users` API endpoint supports [response filtering][3] for a subset of user data based on labels and the following fields: + +- `user.username` +- `user.disabled` +- `user.groups` + +### Example + +The following example demonstrates a request to the `/users` API endpoint with [response filtering][3] for only [user definitions][1] whose user.groups include `dev`: + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/users -G \ +--data-urlencode 'fieldSelector="dev" in user.groups' +{{< /code >}} + +The example request will result in a successful `HTTP/1.1 200 OK` response and a JSON array that contains only [user definitions][1] whose user.groups include `dev`: + +{{< code text >}} +[ + { + "username": "alice", + "groups": [ + "ops", + "dev" + ], + "disabled": false + }, + { + "username": "balan", + "groups": [ + "testing", + "dev" + ], + "disabled": false + } +] +{{< /code >}} + +{{% notice note %}} +**NOTE**: Read [API response filtering](../../#response-filtering) for more filter statement examples that demonstrate how to filter responses using different operators with label and field selectors. +{{% /notice %}} + +### API Specification + +/users (GET) with response filters | +---------------|------ +description | Returns the list of users that match the [response filters][8] applied in the API request. +example url | http://hostname:8080/api/core/v2/users +pagination | This endpoint supports [pagination][2] using the `limit` and `continue` query parameters. +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "username": "alice", + "groups": [ + "ops", + "dev" + ], + "disabled": false + }, + { + "username": "balan", + "groups": [ + "testing", + "dev" + ], + "disabled": false + } +] +{{< /code >}} + + +[1]: ../../../operations/control-access/rbac#users +[2]: ../../#pagination +[3]: https://en.wikipedia.org/wiki/Bcrypt +[4]: ../../../sensuctl/#generate-a-password-hash +[8]: ../../#response-filtering diff --git a/content/sensu-go/6.12/api/enterprise/_index.md b/content/sensu-go/6.12/api/enterprise/_index.md new file mode 100644 index 0000000000..fa427bc77f --- /dev/null +++ b/content/sensu-go/6.12/api/enterprise/_index.md @@ -0,0 +1,23 @@ +--- +title: "Enterprise APIs" +description: "Use Sensu's enterprise APIs for programmatic access to commercial features like federation, secrets management, single sign-on (SSO) authentication, and more." +product: "Sensu Go" +version: "6.12" +weight: 20 +layout: "single" +toc: false +menu: + sensu-go-6.12: + parent: api + identifier: enterprise +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access Sensu's enterprise APIs in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../commercial/). +{{% /notice %}} + +Sensu's enterprise APIs provide programmatic access to commercial features. +The enterprise APIs include: + +{{< enterpriseapiListing >}} diff --git a/content/sensu-go/6.12/api/enterprise/authproviders.md b/content/sensu-go/6.12/api/enterprise/authproviders.md new file mode 100644 index 0000000000..22e7aa62d1 --- /dev/null +++ b/content/sensu-go/6.12/api/enterprise/authproviders.md @@ -0,0 +1,396 @@ +--- +title: "enterprise/authentication/v2" +description: "Read this API documentation to use Sensu enterprise/authentication/v2 endpoints for HTTP access to single sign-on (SSO) authentication provider configurations." +enterprise_api_title: "enterprise/authentication/v2" +type: "enterprise_api" +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: enterprise +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access authentication providers for single sign-on (SSO) in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} + +{{% notice note %}} +**NOTE**: Requests to `enterprise/authentication/v2` API endpoints require you to authenticate with a Sensu [API key](../../#configure-an-environment-variable-for-api-key-authentication) or [access token](../../#authenticate-with-auth-api-endpoints). +The code examples in this document use the [environment variable](../../#configure-an-environment-variable-for-api-key-authentication) `$SENSU_API_KEY` to represent a valid API key in API requests. +{{% /notice %}} + +## Get active authentication provider configurations {#authproviders-get} + +The `/authproviders` API endpoint provides HTTP GET access to authentication provider configuration in Sensu. + +### Example {#authproviders-get-example} + +The following example queries the `/authproviders` API endpoint for the authentication provider configurations in Sensu: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/enterprise/authentication/v2/authproviders \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request results in a successful `HTTP/1.1 200 OK` response and a JSON array that contains the [authentication provider configurations][1]: + +{{< code text >}} +[ + { + "type": "oidc", + "api_version": "authentication/v2", + "metadata": { + "name": "oidc_auth", + "created_by": "admin" + }, + "spec": { + "additional_scopes": [ + "groups", + "email" + ], + "client_id": "xxxxxxxxxxxxxxxxxxxx", + "client_secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", + "disable_offline_access": false, + "groups_claim": "groups", + "groups_prefix": "oidc:", + "redirect_uri": "http://sensu-backend.example.com:8080/api/enterprise/authentication/v2/oidc/callback", + "server": "https://oidc.example.com:9031", + "username_claim": "email", + "username_prefix": "oidc:" + } + }, + { + "type": "ldap", + "api_version": "authentication/v2", + "metadata": { + "name": "openldap", + "created_by": "admin" + }, + "spec": { + "groups_prefix": "", + "servers": [ + { + "binding": { + "password": "YOUR_PASSWORD", + "user_dn": "cn=binder,dc=acme,dc=org" + }, + "client_cert_file": "", + "client_key_file": "", + "default_upn_domain": "", + "group_search": { + "attribute": "member", + "base_dn": "dc=acme,dc=org", + "name_attribute": "cn", + "object_class": "groupOfNames" + }, + "host": "127.0.0.1", + "insecure": false, + "port": 636, + "security": "tls", + "trusted_ca_file": "", + "user_search": { + "attribute": "uid", + "base_dn": "dc=acme,dc=org", + "name_attribute": "cn", + "object_class": "person" + } + } + ], + "username_prefix": "" + } + } +] +{{< /code >}} + +### API Specification {#authproviders-get-specification} + +/authproviders (GET) | +---------------|------ +description | Returns the list of active authentication providers. +example url | http://hostname:8080/api/enterprise/authentication/v2/authproviders +query parameters | `types`: Defines which type of authentication provider to retrieve. Join with `&` to retrieve multiple types: `?types=AD&types=OIDC`. +pagination | This endpoint supports pagination using the `limit` and `continue` query parameters. Read the [API overview][3] for details. +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "type": "oidc", + "api_version": "authentication/v2", + "metadata": { + "name": "oidc_auth", + "created_by": "admin" + }, + "spec": { + "additional_scopes": [ + "groups", + "email" + ], + "client_id": "xxxxxxxxxxxxxxxxxxxx", + "client_secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", + "disable_offline_access": false, + "groups_claim": "groups", + "groups_prefix": "oidc:", + "redirect_uri": "http://sensu-backend.example.com:8080/api/enterprise/authentication/v2/oidc/callback", + "server": "https://oidc.example.com:9031", + "username_claim": "email", + "username_prefix": "oidc:" + } + }, + { + "type": "ldap", + "api_version": "authentication/v2", + "metadata": { + "name": "openldap", + "created_by": "admin" + }, + "spec": { + "groups_prefix": "", + "servers": [ + { + "binding": { + "password": "YOUR_PASSWORD", + "user_dn": "cn=binder,dc=acme,dc=org" + }, + "client_cert_file": "", + "client_key_file": "", + "default_upn_domain": "", + "group_search": { + "attribute": "member", + "base_dn": "dc=acme,dc=org", + "name_attribute": "cn", + "object_class": "groupOfNames" + }, + "host": "127.0.0.1", + "insecure": false, + "port": 636, + "security": "tls", + "trusted_ca_file": "", + "user_search": { + "attribute": "uid", + "base_dn": "dc=acme,dc=org", + "name_attribute": "cn", + "object_class": "person" + } + } + ], + "username_prefix": "" + } + } +] +{{< /code >}} + +## Get the configuration for a specific authentication provider {#authprovidersname-get} + +The `/authproviders/:name` API endpoint provides HTTP GET access to the authentication provider configuration for a specific `:name`. + +### Example {#authprovidersname-get-example} + +In the following example, an HTTP GET request is submitted to the `/authproviders/:name` API endpoint to retrieve the `openldap` authenthication provider configuration: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/enterprise/authentication/v2/authproviders/openldap \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' +{{< /code >}} + +The request will return a successful `HTTP/1.1 200 OK` response and a JSON map that contains the requested authentication provider [`:name` definition][1] (in this example, `openldap`): + +{{< code shell >}} +{ + "type": "ldap", + "api_version": "authentication/v2", + "metadata": { + "name": "openldap", + "created_by": "admin" + }, + "spec": { + "groups_prefix": "", + "servers": [ + { + "binding": { + "password": "YOUR_PASSWORD", + "user_dn": "cn=binder,dc=acme,dc=org" + }, + "client_cert_file": "", + "client_key_file": "", + "default_upn_domain": "", + "group_search": { + "attribute": "member", + "base_dn": "dc=acme,dc=org", + "name_attribute": "cn", + "object_class": "groupOfNames" + }, + "host": "127.0.0.1", + "insecure": false, + "port": 636, + "security": "tls", + "trusted_ca_file": "", + "user_search": { + "attribute": "uid", + "base_dn": "dc=acme,dc=org", + "name_attribute": "cn", + "object_class": "person" + } + } + ], + "username_prefix": "" + } +} +{{< /code >}} + +### API Specification {#authprovidersname-get-specification} + +/authproviders/:name (GET) | +---------------------|------ +description | Returns the configuration for an authentication provider for the specified configured provider name. +example url | http://hostname:8080/api/enterprise/authentication/v2/authproviders/openldap +response type | Map +response codes |
    • **Success**: 200 (OK)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +{ + "type": "ldap", + "api_version": "authentication/v2", + "metadata": { + "name": "openldap", + "created_by": "admin" + }, + "spec": { + "groups_prefix": "", + "servers": [ + { + "binding": { + "password": "YOUR_PASSWORD", + "user_dn": "cn=binder,dc=acme,dc=org" + }, + "client_cert_file": "", + "client_key_file": "", + "default_upn_domain": "", + "group_search": { + "attribute": "member", + "base_dn": "dc=acme,dc=org", + "name_attribute": "cn", + "object_class": "groupOfNames" + }, + "host": "127.0.0.1", + "insecure": false, + "port": 636, + "security": "tls", + "trusted_ca_file": "", + "user_search": { + "attribute": "uid", + "base_dn": "dc=acme,dc=org", + "name_attribute": "cn", + "object_class": "person" + } + } + ], + "username_prefix": "" + } +} +{{< /code >}} + +## Create or update the configuration for a specific authentication provider {#authprovidersname-put} + +The `/authproviders/:name` API endpoint provides HTTP PUT access to create or update the [authentication provider][1] configuration for a specific `:name`. + +### Example {#authprovidersname-put-example} + +In the following example, an HTTP PUT request is submitted to the `/authproviders/:name` API endpoint to create the `openldap` authenthication provider: + +{{< code shell >}} +curl -X PUT \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "Type": "ldap", + "api_version": "authentication/v2", + "spec": { + "servers": [ + { + "host": "127.0.0.1", + "binding": { + "user_dn": "cn=binder,dc=acme,dc=org", + "password": "YOUR_PASSWORD" + }, + "group_search": { + "base_dn": "dc=acme,dc=org" + }, + "user_search": { + "base_dn": "dc=acme,dc=org" + } + } + ] + }, + "metadata": { + "name": "openldap" + } +}' \ +http://127.0.0.1:8080/api/enterprise/authentication/v2/authproviders/openldap +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#authprovidersname-put-specification} + +/authproviders/:name (PUT) | +----------------|------ +description | Creates or updates the authentication provider configuration for the specified name. Read the [authentication guide][1] for more information about supported providers. +example url | http://hostname:8080/api/enterprise/authentication/v2/authproviders/openldap +payload | {{< code json >}} +{ + "Type": "ldap", + "api_version": "authentication/v2", + "spec": { + "servers": [ + { + "host": "127.0.0.1", + "binding": { + "user_dn": "cn=binder,dc=acme,dc=org", + "password": "YOUR_PASSWORD" + }, + "group_search": { + "base_dn": "dc=acme,dc=org" + }, + "user_search": { + "base_dn": "dc=acme,dc=org" + } + } + ] + }, + "metadata": { + "name": "openldap" + } +} +{{< /code >}} +payload parameters | All attributes shown in the example payload are required. For more information about configuring authentication providers, read the [authentication guide][1]. +response codes |
    • **Success**: 200 (OK)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Delete the configuration for a specific authentication provider {#authprovidersname-delete} + +The `/authproviders/:name` API endpoint provides HTTP DELETE access to delete the authentication provider configuration from Sensu for a specific `:name`. + +### Example {#authprovidersname-delete-example} + +The following example shows a request to the `/authproviders/:name` API endpoint to delete the configuration for the authentication provider `openldap`, resulting in a successful `HTTP/1.1 204 No Content` response: + +{{< code shell >}} +curl -X DELETE \ +-H "Authorization: Key $SENSU_API_KEY" \ +http://127.0.0.1:8080/api/core/v2/namespaces/default/authproviders/openldap +{{< /code >}} + +### API Specification {#authprovidersname-delete-specification} + +/authproviders/:name (DELETE) | +--------------------------|------ +description | Deletes the authentication provider configuration from Sensu for the specified name. +example url | http://hostname:8080/api/enterprise/authentication/v2/authproviders/openldap +response codes |
    • **Success**: 204 (No Content)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + + +[1]: ../../../operations/control-access/sso/ +[3]: ../../#pagination diff --git a/content/sensu-go/6.12/api/enterprise/business-service-monitoring.md b/content/sensu-go/6.12/api/enterprise/business-service-monitoring.md new file mode 100644 index 0000000000..4c1dafc013 --- /dev/null +++ b/content/sensu-go/6.12/api/enterprise/business-service-monitoring.md @@ -0,0 +1,986 @@ +--- +title: "enterprise/bsm/v1" +description: "Read this API documentation for information about Sensu enterprise/bsm/v1 API endpoints, with examples for configuring business service monitoring resources." +enterprise_api_title: "enterprise/bsm/v1" +type: "enterprise_api" +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: enterprise +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access business service monitoring (BSM) in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} + +{{% notice note %}} +**NOTE**: Business service monitoring (BSM) is in public preview and is subject to change.

    +Requests to `enterprise/bsm/v1` API endpoints require you to authenticate with a Sensu [API key](../../#configure-an-environment-variable-for-api-key-authentication) or [access token](../../#authenticate-with-auth-api-endpoints). +The code examples in this document use the [environment variable](../../#configure-an-environment-variable-for-api-key-authentication) `$SENSU_API_KEY` to represent a valid API key in API requests. +{{% /notice %}} + +## Get all service components + +The `/service-components` API endpoint provides HTTP GET access to a list of service components. + +### Example + +The following example demonstrates a GET request to the `/service-components` API endpoint: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/enterprise/bsm/v1/namespaces/default/service-components \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request results in a successful `HTTP/1.1 200 OK` response and a JSON array that contains the [service component definitions][1] in the `default` namespace: + +{{< code text >}} +[ + { + "type": "ServiceComponent", + "api_version": "bsm/v1", + "metadata": { + "name": "webservers", + "namespace": "default", + "created_by": "admin" + }, + "spec": { + "cron": "", + "handlers": [ + "slack" + ], + "interval": 60, + "query": [ + { + "type": "fieldSelector", + "value": "webserver in event.check.subscriptions" + } + ], + "rules": [ + { + "arguments": { + "critical_threshold": 70, + "warning_threshold": 50 + }, + "name": "webservers_50-70", + "template": "aggregate" + } + ], + "services": [ + "website-services" + ] + } + } +] +{{< /code >}} + +### API Specification + +/service-components (GET) | +---------------|------ +description | Returns the list of service components. +example url | http://hostname:8080/api/enterprise/bsm/v1/namespaces/default/service-components +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "type": "ServiceComponent", + "api_version": "bsm/v1", + "metadata": { + "name": "webservers", + "namespace": "default", + "created_by": "admin" + }, + "spec": { + "cron": "", + "handlers": [ + "slack" + ], + "interval": 60, + "query": [ + { + "type": "fieldSelector", + "value": "webserver in event.check.subscriptions" + } + ], + "rules": [ + { + "arguments": { + "critical_threshold": 70, + "warning_threshold": 50 + }, + "name": "webservers_50-70", + "template": "aggregate" + } + ], + "services": [ + "website-services" + ] + } + } +] +{{< /code >}} + +## Create a new service component + +The `/service-components` API endpoint provides HTTP POST access to create service components. + +### Example + +The following example demonstrates a request to the `/service-components` API endpoint to create the service component `webservers`: + +{{< code shell >}} +curl -X POST \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "type": "ServiceComponent", + "api_version": "bsm/v1", + "metadata": { + "name": "webservers" + }, + "spec": { + "cron": "", + "handlers": [ + "slack" + ], + "interval": 60, + "query": [ + { + "type": "fieldSelector", + "value": "webserver in event.check.subscriptions" + } + ], + "rules": [ + { + "arguments": { + "critical_threshold": 70, + "warning_threshold": 50 + }, + "name": "webservers_50-70", + "template": "aggregate" + } + ], + "services": [ + "website-services" + ] + } +}' \ +http://127.0.0.1:8080/api/enterprise/bsm/v1/namespaces/default/service-components +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification + +/service-components (POST) | +----------------|------ +description | Creates a new business service component (if none exists). +example URL | http://hostname:8080/api/enterprise/bsm/v1/namespaces/default/service-components +payload | {{< code json >}} +{ + "type": "ServiceComponent", + "api_version": "bsm/v1", + "metadata": { + "name": "webservers" + }, + "spec": { + "cron": "", + "handlers": [ + "slack" + ], + "interval": 60, + "query": [ + { + "type": "fieldSelector", + "value": "webserver in event.check.subscriptions" + } + ], + "rules": [ + { + "arguments": { + "critical_threshold": 70, + "warning_threshold": 50 + }, + "name": "webservers_50-70", + "template": "aggregate" + } + ], + "services": [ + "website-services" + ] + } +} +{{< /code >}} +response codes |
    • **Success**: 200 (OK)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Get a specific service component + +The `/service-components/:service-component` API endpoint provides HTTP GET access to data for a specific `:service-component`, by service compnent name. + +### Example + +The following example queries the `/service-components/:service-component` API endpoint for a specific `:service-component`: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/enterprise/bsm/v1/namespaces/default/service-components/webservers \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request will return a successful `HTTP/1.1 200 OK` response and a JSON map that contains the requested [`:service-component` definition][1] (in this example, `webservers`): + +{{< code text >}} +{ + "type": "ServiceComponent", + "api_version": "bsm/v1", + "metadata": { + "name": "webservers", + "namespace": "default", + "created_by": "admin" + }, + "spec": { + "cron": "", + "handlers": [ + "slack" + ], + "interval": 60, + "query": [ + { + "type": "fieldSelector", + "value": "webserver in event.check.subscriptions" + } + ], + "rules": [ + { + "arguments": { + "critical_threshold": 70, + "warning_threshold": 50 + }, + "name": "webservers_50-70", + "template": "aggregate" + } + ], + "services": [ + "website-services" + ] + } +} +{{< /code >}} + +### API Specification + +/service-components/:service-component (GET) | +---------------------|------ +description | Returns the specified business service component. +example url | http://hostname:8080/api/enterprise/bsm/v1/namespaces/default/service-components/webservers +response type | Map +response codes |
    • **Success**: 200 (OK)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +{ + "type": "ServiceComponent", + "api_version": "bsm/v1", + "metadata": { + "name": "webservers", + "namespace": "default", + "created_by": "admin" + }, + "spec": { + "cron": "", + "handlers": [ + "slack" + ], + "interval": 60, + "query": [ + { + "type": "fieldSelector", + "value": "webserver in event.check.subscriptions" + } + ], + "rules": [ + { + "arguments": { + "critical_threshold": 70, + "warning_threshold": 50 + }, + "name": "webservers_50-70", + "template": "aggregate" + } + ], + "services": [ + "website-services" + ] + } +} +{{< /code >}} + +## Create or update a service component + +The `/service-components/:service-component` API endpoint provides HTTP PUT access to create or update a specific `:service-component`, by service component name. + +### Example + +The following example demonstrates a request to the `/service-components/:service-component` API endpoint to update the service component `webservers`: + +{{< code shell >}} +curl -X PUT \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "type": "ServiceComponent", + "api_version": "bsm/v1", + "metadata": { + "name": "webservers" + }, + "spec": { + "cron": "", + "handlers": [ + "slack" + ], + "interval": 60, + "query": [ + { + "type": "fieldSelector", + "value": "webserver in event.check.subscriptions" + } + ], + "rules": [ + { + "arguments": { + "critical_threshold": 70, + "warning_threshold": 50 + }, + "name": "webservers_50-70", + "template": "aggregate" + } + ], + "services": [ + "website-services" + ] + } +}' \ +http://127.0.0.1:8080/api/enterprise/bsm/v1/namespaces/default/service-components/webservers +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification + +/service-components/:service-component (PUT) | +----------------|------ +description | Creates or updates the specified business service component. +example URL | http://hostname:8080/api/enterprise/bsm/v1/namespaces/default/service-components/webservers +payload | {{< code json >}} +{ + "type": "ServiceComponent", + "api_version": "bsm/v1", + "metadata": { + "name": "webservers" + }, + "spec": { + "cron": "", + "handlers": [ + "slack" + ], + "interval": 60, + "query": [ + { + "type": "fieldSelector", + "value": "webserver in event.check.subscriptions" + } + ], + "rules": [ + { + "arguments": { + "critical_threshold": 70, + "warning_threshold": 50 + }, + "name": "webservers_50-70", + "template": "aggregate" + } + ], + "services": [ + "website-services" + ] + } +} +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Delete a service component + +The `/service-components/:service-component` API endpoint provides HTTP DELETE access to delete the specified service component from Sensu. + +### Example + +The following example shows a request to the `/service-components/:service-component` API endpoint to delete the service component `webservers`, resulting in a successful `HTTP/1.1 204 No Content` response: + +{{< code shell >}} +curl -X DELETE \ +-H "Authorization: Key $SENSU_API_KEY" \ +http://127.0.0.1:8080/api/enterprise/bsm/v1/namespaces/default/service-components/webservers +{{< /code >}} + +### API Specification + +/service-components/:service-component (DELETE) | +--------------------------|------ +description | Deletes the specified business service component from Sensu. +example url | http://hostname:8080/api/enterprise/bsm/v1/namespaces/default/service-components/webservers +response codes |
    • **Success**: 204 (No Content)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + +## Get all rule templates + +The `/rule-templates` API endpoint provides HTTP GET access to a list of rule templates. + +### Example + +The following example demonstrates a GET request to the `/rule-templates` API endpoint: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/enterprise/bsm/v1/namespaces/default/rule-templates \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request results in a successful `HTTP/1.1 200 OK` response and a JSON array that contains the [rule template definitions][2] in the `default` namespace: + +{{< code text >}} +[ + { + "type": "RuleTemplate", + "api_version": "bsm/v1", + "metadata": { + "name": "aggregate", + "namespace": "default", + "created_by": "admin" + }, + "spec": { + "arguments": { + "properties": { + "critical_count": { + "description": "create an event with a critical status if there the number of critical events is equal to or greater than this count", + "type": "number" + }, + "critical_threshold": { + "description": "create an event with a critical status if the percentage of non-zero events is equal to or greater than this threshold", + "type": "number" + }, + "metric_handlers": { + "default": {}, + "description": "metric handlers to use for produced metrics", + "items": { + "type": "string" + }, + "type": "array" + }, + "produce_metrics": { + "default": {}, + "description": "produce metrics from aggregate data and include them in the produced event", + "type": "boolean" + }, + "set_metric_annotations": { + "default": {}, + "description": "annotate the produced event with metric annotations", + "type": "boolean" + }, + "warning_count": { + "description": "create an event with a warning status if there the number of critical events is equal to or greater than this count", + "type": "number" + }, + "warning_threshold": { + "description": "create an event with a warning status if the percentage of non-zero events is equal to or greater than this threshold", + "type": "number" + } + }, + "required": null + }, + "description": "Monitor a distributed service - aggregate one or more events into a single event. This BSM rule template allows you to treat the results of multiple disparate check executions – executed across multiple disparate systems – as a single event. This template is extremely useful in dynamic environments and/or environments that have a reasonable tolerance for failure. Use this template when a service can be considered healthy as long as a minimum threshold is satisfied (for example, at least 5 healthy web servers? at least 70% of N processes healthy?).", + "eval": "\nif (events && events.length == 0) {\n event.check.output = \"WARNING: No events selected for aggregate\n\";\n event.check.status = 1;\n return event;\n}\n\nevent.annotations[\"io.sensu.bsm.selected_event_count\"] = events.length;\n\npercentOK = sensu.PercentageBySeverity(\"ok\");\n\nif (!!args[\"produce_metrics\"]) {\n var handlers = [];\n\n if (!!args[\"metric_handlers\"]) {\n handlers = args[\"metric_handlers\"].slice();\n }\n\n var ts = Math.floor(new Date().getTime() / 1000);\n\n event.timestamp = ts;\n\n var tags = [\n {\n name: \"service\",\n value: event.entity.name\n },\n {\n name: \"entity\",\n value: event.entity.name\n },\n {\n name: \"check\",\n value: event.check.name\n }\n ];\n\n event.metrics = sensu.NewMetrics({\n handlers: handlers,\n points: [\n {\n name: \"percent_non_zero\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"non-zero\"),\n tags: tags\n },\n {\n name: \"percent_ok\",\n timestamp: ts,\n value: percentOK,\n tags: tags\n },\n {\n name: \"percent_warning\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"warning\"),\n tags: tags\n },\n {\n name: \"percent_critical\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"critical\"),\n tags: tags\n },\n {\n name: \"percent_unknown\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"unknown\"),\n tags: tags\n },\n {\n name: \"count_non_zero\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"non-zero\"),\n tags: tags\n },\n {\n name: \"count_ok\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"ok\"),\n tags: tags\n },\n {\n name: \"count_warning\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"warning\"),\n tags: tags\n },\n {\n name: \"count_critical\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"critical\"),\n tags: tags\n },\n {\n name: \"count_unknown\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"unknown\"),\n tags: tags\n }\n ]\n });\n\n if (!!args[\"set_metric_annotations\"]) {\n var i = 0;\n\n while(i < event.metrics.points.length) {\n event.annotations[\"io.sensu.bsm.selected_event_\" + event.metrics.points[i].name] = event.metrics.points[i].value.toString();\n i++;\n }\n }\n}\n\nif (!!args[\"critical_threshold\"] && percentOK <= args[\"critical_threshold\"]) {\n event.check.output = \"CRITICAL: Less than \" + args[\"critical_threshold\"].toString() + \"% of selected events are OK (\" + percentOK.toString() + \"%)\n\";\n event.check.status = 2;\n return event;\n}\n\nif (!!args[\"warning_threshold\"] && percentOK <= args[\"warning_threshold\"]) {\n event.check.output = \"WARNING: Less than \" + args[\"warning_threshold\"].toString() + \"% of selected events are OK (\" + percentOK.toString() + \"%)\n\";\n event.check.status = 1;\n return event;\n}\n\nif (!!args[\"critical_count\"]) {\n crit = sensu.CountBySeverity(\"critical\");\n\n if (crit >= args[\"critical_count\"]) {\n event.check.output = \"CRITICAL: \" + args[\"critical_count\"].toString() + \" or more selected events are in a critical state (\" + crit.toString() + \")\n\";\n event.check.status = 2;\n return event;\n }\n}\n\nif (!!args[\"warning_count\"]) {\n warn = sensu.CountBySeverity(\"warning\");\n\n if (warn >= args[\"warning_count\"]) {\n event.check.output = \"WARNING: \" + args[\"warning_count\"].toString() + \" or more selected events are in a warning state (\" + warn.toString() + \")\n\";\n event.check.status = 1;\n return event;\n }\n}\n\nevent.check.output = \"Everything looks good (\" + percentOK.toString() + \"% OK)\";\nevent.check.status = 0;\n\nreturn event;\n" + } + } +] +{{< /code >}} + +### API Specification + +/rule-templates (GET) | +---------------|------ +description | Returns the list of rule templates. +example url | http://hostname:8080/api/enterprise/bsm/v1/namespaces/default/rule-templates +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "type": "RuleTemplate", + "api_version": "bsm/v1", + "metadata": { + "name": "aggregate", + "namespace": "default", + "created_by": "admin" + }, + "spec": { + "arguments": { + "properties": { + "critical_count": { + "description": "create an event with a critical status if there the number of critical events is equal to or greater than this count", + "type": "number" + }, + "critical_threshold": { + "description": "create an event with a critical status if the percentage of non-zero events is equal to or greater than this threshold", + "type": "number" + }, + "metric_handlers": { + "default": {}, + "description": "metric handlers to use for produced metrics", + "items": { + "type": "string" + }, + "type": "array" + }, + "produce_metrics": { + "default": {}, + "description": "produce metrics from aggregate data and include them in the produced event", + "type": "boolean" + }, + "set_metric_annotations": { + "default": {}, + "description": "annotate the produced event with metric annotations", + "type": "boolean" + }, + "warning_count": { + "description": "create an event with a warning status if there the number of critical events is equal to or greater than this count", + "type": "number" + }, + "warning_threshold": { + "description": "create an event with a warning status if the percentage of non-zero events is equal to or greater than this threshold", + "type": "number" + } + }, + "required": null + }, + "description": "Monitor a distributed service - aggregate one or more events into a single event. This BSM rule template allows you to treat the results of multiple disparate check executions – executed across multiple disparate systems – as a single event. This template is extremely useful in dynamic environments and/or environments that have a reasonable tolerance for failure. Use this template when a service can be considered healthy as long as a minimum threshold is satisfied (for example, at least 5 healthy web servers? at least 70% of N processes healthy?).", + "eval": "\nif (events && events.length == 0) {\n event.check.output = \"WARNING: No events selected for aggregate\n\";\n event.check.status = 1;\n return event;\n}\n\nevent.annotations[\"io.sensu.bsm.selected_event_count\"] = events.length;\n\npercentOK = sensu.PercentageBySeverity(\"ok\");\n\nif (!!args[\"produce_metrics\"]) {\n var handlers = [];\n\n if (!!args[\"metric_handlers\"]) {\n handlers = args[\"metric_handlers\"].slice();\n }\n\n var ts = Math.floor(new Date().getTime() / 1000);\n\n event.timestamp = ts;\n\n var tags = [\n {\n name: \"service\",\n value: event.entity.name\n },\n {\n name: \"entity\",\n value: event.entity.name\n },\n {\n name: \"check\",\n value: event.check.name\n }\n ];\n\n event.metrics = sensu.NewMetrics({\n handlers: handlers,\n points: [\n {\n name: \"percent_non_zero\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"non-zero\"),\n tags: tags\n },\n {\n name: \"percent_ok\",\n timestamp: ts,\n value: percentOK,\n tags: tags\n },\n {\n name: \"percent_warning\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"warning\"),\n tags: tags\n },\n {\n name: \"percent_critical\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"critical\"),\n tags: tags\n },\n {\n name: \"percent_unknown\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"unknown\"),\n tags: tags\n },\n {\n name: \"count_non_zero\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"non-zero\"),\n tags: tags\n },\n {\n name: \"count_ok\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"ok\"),\n tags: tags\n },\n {\n name: \"count_warning\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"warning\"),\n tags: tags\n },\n {\n name: \"count_critical\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"critical\"),\n tags: tags\n },\n {\n name: \"count_unknown\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"unknown\"),\n tags: tags\n }\n ]\n });\n\n if (!!args[\"set_metric_annotations\"]) {\n var i = 0;\n\n while(i < event.metrics.points.length) {\n event.annotations[\"io.sensu.bsm.selected_event_\" + event.metrics.points[i].name] = event.metrics.points[i].value.toString();\n i++;\n }\n }\n}\n\nif (!!args[\"critical_threshold\"] && percentOK <= args[\"critical_threshold\"]) {\n event.check.output = \"CRITICAL: Less than \" + args[\"critical_threshold\"].toString() + \"% of selected events are OK (\" + percentOK.toString() + \"%)\n\";\n event.check.status = 2;\n return event;\n}\n\nif (!!args[\"warning_threshold\"] && percentOK <= args[\"warning_threshold\"]) {\n event.check.output = \"WARNING: Less than \" + args[\"warning_threshold\"].toString() + \"% of selected events are OK (\" + percentOK.toString() + \"%)\n\";\n event.check.status = 1;\n return event;\n}\n\nif (!!args[\"critical_count\"]) {\n crit = sensu.CountBySeverity(\"critical\");\n\n if (crit >= args[\"critical_count\"]) {\n event.check.output = \"CRITICAL: \" + args[\"critical_count\"].toString() + \" or more selected events are in a critical state (\" + crit.toString() + \")\n\";\n event.check.status = 2;\n return event;\n }\n}\n\nif (!!args[\"warning_count\"]) {\n warn = sensu.CountBySeverity(\"warning\");\n\n if (warn >= args[\"warning_count\"]) {\n event.check.output = \"WARNING: \" + args[\"warning_count\"].toString() + \" or more selected events are in a warning state (\" + warn.toString() + \")\n\";\n event.check.status = 1;\n return event;\n }\n}\n\nevent.check.output = \"Everything looks good (\" + percentOK.toString() + \"% OK)\";\nevent.check.status = 0;\n\nreturn event;\n" + } + } +] +{{< /code >}} + +## Create a new rule template + +The `/rule-templates` API endpoint provides HTTP POST access to create rule templates. + +### Example + +The following example demonstrates a request to the `/rule-templates` API endpoint to create the rule template `aggregate`: + +{{< code shell >}} +curl -X POST \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "type": "RuleTemplate", + "api_version": "bsm/v1", + "metadata": { + "name": "aggregate" + }, + "spec": { + "arguments": { + "properties": { + "critical_count": { + "description": "create an event with a critical status if there the number of critical events is equal to or greater than this count", + "type": "number" + }, + "critical_threshold": { + "description": "create an event with a critical status if the percentage of non-zero events is equal to or greater than this threshold", + "type": "number" + }, + "metric_handlers": { + "default": {}, + "description": "metric handlers to use for produced metrics", + "items": { + "type": "string" + }, + "type": "array" + }, + "produce_metrics": { + "default": {}, + "description": "produce metrics from aggregate data and include them in the produced event", + "type": "boolean" + }, + "set_metric_annotations": { + "default": {}, + "description": "annotate the produced event with metric annotations", + "type": "boolean" + }, + "warning_count": { + "description": "create an event with a warning status if there the number of critical events is equal to or greater than this count", + "type": "number" + }, + "warning_threshold": { + "description": "create an event with a warning status if the percentage of non-zero events is equal to or greater than this threshold", + "type": "number" + } + }, + "required": null + }, + "description": "Monitor a distributed service - aggregate one or more events into a single event. This BSM rule template allows you to treat the results of multiple disparate check executions – executed across multiple disparate systems – as a single event. This template is extremely useful in dynamic environments and/or environments that have a reasonable tolerance for failure. Use this template when a service can be considered healthy as long as a minimum threshold is satisfied (for example, at least 5 healthy web servers? at least 70% of N processes healthy?).", + "eval": "\nif (events && events.length == 0) {\n event.check.output = \"WARNING: No events selected for aggregate\n\";\n event.check.status = 1;\n return event;\n}\n\nevent.annotations[\"io.sensu.bsm.selected_event_count\"] = events.length;\n\npercentOK = sensu.PercentageBySeverity(\"ok\");\n\nif (!!args[\"produce_metrics\"]) {\n var handlers = [];\n\n if (!!args[\"metric_handlers\"]) {\n handlers = args[\"metric_handlers\"].slice();\n }\n\n var ts = Math.floor(new Date().getTime() / 1000);\n\n event.timestamp = ts;\n\n var tags = [\n {\n name: \"service\",\n value: event.entity.name\n },\n {\n name: \"entity\",\n value: event.entity.name\n },\n {\n name: \"check\",\n value: event.check.name\n }\n ];\n\n event.metrics = sensu.NewMetrics({\n handlers: handlers,\n points: [\n {\n name: \"percent_non_zero\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"non-zero\"),\n tags: tags\n },\n {\n name: \"percent_ok\",\n timestamp: ts,\n value: percentOK,\n tags: tags\n },\n {\n name: \"percent_warning\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"warning\"),\n tags: tags\n },\n {\n name: \"percent_critical\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"critical\"),\n tags: tags\n },\n {\n name: \"percent_unknown\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"unknown\"),\n tags: tags\n },\n {\n name: \"count_non_zero\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"non-zero\"),\n tags: tags\n },\n {\n name: \"count_ok\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"ok\"),\n tags: tags\n },\n {\n name: \"count_warning\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"warning\"),\n tags: tags\n },\n {\n name: \"count_critical\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"critical\"),\n tags: tags\n },\n {\n name: \"count_unknown\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"unknown\"),\n tags: tags\n }\n ]\n });\n\n if (!!args[\"set_metric_annotations\"]) {\n var i = 0;\n\n while(i < event.metrics.points.length) {\n event.annotations[\"io.sensu.bsm.selected_event_\" + event.metrics.points[i].name] = event.metrics.points[i].value.toString();\n i++;\n }\n }\n}\n\nif (!!args[\"critical_threshold\"] && percentOK <= args[\"critical_threshold\"]) {\n event.check.output = \"CRITICAL: Less than \" + args[\"critical_threshold\"].toString() + \"% of selected events are OK (\" + percentOK.toString() + \"%)\n\";\n event.check.status = 2;\n return event;\n}\n\nif (!!args[\"warning_threshold\"] && percentOK <= args[\"warning_threshold\"]) {\n event.check.output = \"WARNING: Less than \" + args[\"warning_threshold\"].toString() + \"% of selected events are OK (\" + percentOK.toString() + \"%)\n\";\n event.check.status = 1;\n return event;\n}\n\nif (!!args[\"critical_count\"]) {\n crit = sensu.CountBySeverity(\"critical\");\n\n if (crit >= args[\"critical_count\"]) {\n event.check.output = \"CRITICAL: \" + args[\"critical_count\"].toString() + \" or more selected events are in a critical state (\" + crit.toString() + \")\n\";\n event.check.status = 2;\n return event;\n }\n}\n\nif (!!args[\"warning_count\"]) {\n warn = sensu.CountBySeverity(\"warning\");\n\n if (warn >= args[\"warning_count\"]) {\n event.check.output = \"WARNING: \" + args[\"warning_count\"].toString() + \" or more selected events are in a warning state (\" + warn.toString() + \")\n\";\n event.check.status = 1;\n return event;\n }\n}\n\nevent.check.output = \"Everything looks good (\" + percentOK.toString() + \"% OK)\";\nevent.check.status = 0;\n\nreturn event;\n" + } +}' \ +http://127.0.0.1:8080/api/enterprise/bsm/v1/namespaces/default/rule-templates +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification + +/rule-templates (POST) | +----------------|------ +description | Creates a new rule template (if none exists). +example URL | http://hostname:8080/api/enterprise/bsm/v1/namespaces/default/rule-templates +payload | {{< code json >}} +{ + "type": "RuleTemplate", + "api_version": "bsm/v1", + "metadata": { + "name": "aggregate" + }, + "spec": { + "arguments": { + "properties": { + "critical_count": { + "description": "create an event with a critical status if there the number of critical events is equal to or greater than this count", + "type": "number" + }, + "critical_threshold": { + "description": "create an event with a critical status if the percentage of non-zero events is equal to or greater than this threshold", + "type": "number" + }, + "metric_handlers": { + "default": {}, + "description": "metric handlers to use for produced metrics", + "items": { + "type": "string" + }, + "type": "array" + }, + "produce_metrics": { + "default": {}, + "description": "produce metrics from aggregate data and include them in the produced event", + "type": "boolean" + }, + "set_metric_annotations": { + "default": {}, + "description": "annotate the produced event with metric annotations", + "type": "boolean" + }, + "warning_count": { + "description": "create an event with a warning status if there the number of critical events is equal to or greater than this count", + "type": "number" + }, + "warning_threshold": { + "description": "create an event with a warning status if the percentage of non-zero events is equal to or greater than this threshold", + "type": "number" + } + }, + "required": null + }, + "description": "Monitor a distributed service - aggregate one or more events into a single event. This BSM rule template allows you to treat the results of multiple disparate check executions – executed across multiple disparate systems – as a single event. This template is extremely useful in dynamic environments and/or environments that have a reasonable tolerance for failure. Use this template when a service can be considered healthy as long as a minimum threshold is satisfied (for example, at least 5 healthy web servers? at least 70% of N processes healthy?).", + "eval": "\nif (events && events.length == 0) {\n event.check.output = \"WARNING: No events selected for aggregate\n\";\n event.check.status = 1;\n return event;\n}\n\nevent.annotations[\"io.sensu.bsm.selected_event_count\"] = events.length;\n\npercentOK = sensu.PercentageBySeverity(\"ok\");\n\nif (!!args[\"produce_metrics\"]) {\n var handlers = [];\n\n if (!!args[\"metric_handlers\"]) {\n handlers = args[\"metric_handlers\"].slice();\n }\n\n var ts = Math.floor(new Date().getTime() / 1000);\n\n event.timestamp = ts;\n\n var tags = [\n {\n name: \"service\",\n value: event.entity.name\n },\n {\n name: \"entity\",\n value: event.entity.name\n },\n {\n name: \"check\",\n value: event.check.name\n }\n ];\n\n event.metrics = sensu.NewMetrics({\n handlers: handlers,\n points: [\n {\n name: \"percent_non_zero\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"non-zero\"),\n tags: tags\n },\n {\n name: \"percent_ok\",\n timestamp: ts,\n value: percentOK,\n tags: tags\n },\n {\n name: \"percent_warning\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"warning\"),\n tags: tags\n },\n {\n name: \"percent_critical\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"critical\"),\n tags: tags\n },\n {\n name: \"percent_unknown\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"unknown\"),\n tags: tags\n },\n {\n name: \"count_non_zero\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"non-zero\"),\n tags: tags\n },\n {\n name: \"count_ok\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"ok\"),\n tags: tags\n },\n {\n name: \"count_warning\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"warning\"),\n tags: tags\n },\n {\n name: \"count_critical\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"critical\"),\n tags: tags\n },\n {\n name: \"count_unknown\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"unknown\"),\n tags: tags\n }\n ]\n });\n\n if (!!args[\"set_metric_annotations\"]) {\n var i = 0;\n\n while(i < event.metrics.points.length) {\n event.annotations[\"io.sensu.bsm.selected_event_\" + event.metrics.points[i].name] = event.metrics.points[i].value.toString();\n i++;\n }\n }\n}\n\nif (!!args[\"critical_threshold\"] && percentOK <= args[\"critical_threshold\"]) {\n event.check.output = \"CRITICAL: Less than \" + args[\"critical_threshold\"].toString() + \"% of selected events are OK (\" + percentOK.toString() + \"%)\n\";\n event.check.status = 2;\n return event;\n}\n\nif (!!args[\"warning_threshold\"] && percentOK <= args[\"warning_threshold\"]) {\n event.check.output = \"WARNING: Less than \" + args[\"warning_threshold\"].toString() + \"% of selected events are OK (\" + percentOK.toString() + \"%)\n\";\n event.check.status = 1;\n return event;\n}\n\nif (!!args[\"critical_count\"]) {\n crit = sensu.CountBySeverity(\"critical\");\n\n if (crit >= args[\"critical_count\"]) {\n event.check.output = \"CRITICAL: \" + args[\"critical_count\"].toString() + \" or more selected events are in a critical state (\" + crit.toString() + \")\n\";\n event.check.status = 2;\n return event;\n }\n}\n\nif (!!args[\"warning_count\"]) {\n warn = sensu.CountBySeverity(\"warning\");\n\n if (warn >= args[\"warning_count\"]) {\n event.check.output = \"WARNING: \" + args[\"warning_count\"].toString() + \" or more selected events are in a warning state (\" + warn.toString() + \")\n\";\n event.check.status = 1;\n return event;\n }\n}\n\nevent.check.output = \"Everything looks good (\" + percentOK.toString() + \"% OK)\";\nevent.check.status = 0;\n\nreturn event;\n" + } +} +{{< /code >}} +response codes |
    • **Success**: 200 (OK)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Get a specific rule template + +The `/rule-templates/:rule-template` API endpoint provides HTTP GET access to data for a specific rule template by name. + +### Example + +The following example queries the `/rule-templates/:rule-template` API endpoint for a specific `:rule-template`: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/enterprise/bsm/v1/namespaces/default/rule-templates/aggregate \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request will return a successful `HTTP/1.1 200 OK` response and a JSON map that contains the requested [`:rule-template` definition][2] (in this example, `aggregate`): + +{{< code text >}} +{ + "type": "RuleTemplate", + "api_version": "bsm/v1", + "metadata": { + "name": "aggregate", + "namespace": "default", + "created_by": "admin" + }, + "spec": { + "arguments": { + "properties": { + "critical_count": { + "description": "create an event with a critical status if there the number of critical events is equal to or greater than this count", + "type": "number" + }, + "critical_threshold": { + "description": "create an event with a critical status if the percentage of non-zero events is equal to or greater than this threshold", + "type": "number" + }, + "metric_handlers": { + "default": {}, + "description": "metric handlers to use for produced metrics", + "items": { + "type": "string" + }, + "type": "array" + }, + "produce_metrics": { + "default": {}, + "description": "produce metrics from aggregate data and include them in the produced event", + "type": "boolean" + }, + "set_metric_annotations": { + "default": {}, + "description": "annotate the produced event with metric annotations", + "type": "boolean" + }, + "warning_count": { + "description": "create an event with a warning status if there the number of critical events is equal to or greater than this count", + "type": "number" + }, + "warning_threshold": { + "description": "create an event with a warning status if the percentage of non-zero events is equal to or greater than this threshold", + "type": "number" + } + }, + "required": null + }, + "description": "Monitor a distributed service - aggregate one or more events into a single event. This BSM rule template allows you to treat the results of multiple disparate check executions – executed across multiple disparate systems – as a single event. This template is extremely useful in dynamic environments and/or environments that have a reasonable tolerance for failure. Use this template when a service can be considered healthy as long as a minimum threshold is satisfied (for example, at least 5 healthy web servers? at least 70% of N processes healthy?).", + "eval": "\nif (events && events.length == 0) {\n event.check.output = \"WARNING: No events selected for aggregate\n\";\n event.check.status = 1;\n return event;\n}\n\nevent.annotations[\"io.sensu.bsm.selected_event_count\"] = events.length;\n\npercentOK = sensu.PercentageBySeverity(\"ok\");\n\nif (!!args[\"produce_metrics\"]) {\n var handlers = [];\n\n if (!!args[\"metric_handlers\"]) {\n handlers = args[\"metric_handlers\"].slice();\n }\n\n var ts = Math.floor(new Date().getTime() / 1000);\n\n event.timestamp = ts;\n\n var tags = [\n {\n name: \"service\",\n value: event.entity.name\n },\n {\n name: \"entity\",\n value: event.entity.name\n },\n {\n name: \"check\",\n value: event.check.name\n }\n ];\n\n event.metrics = sensu.NewMetrics({\n handlers: handlers,\n points: [\n {\n name: \"percent_non_zero\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"non-zero\"),\n tags: tags\n },\n {\n name: \"percent_ok\",\n timestamp: ts,\n value: percentOK,\n tags: tags\n },\n {\n name: \"percent_warning\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"warning\"),\n tags: tags\n },\n {\n name: \"percent_critical\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"critical\"),\n tags: tags\n },\n {\n name: \"percent_unknown\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"unknown\"),\n tags: tags\n },\n {\n name: \"count_non_zero\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"non-zero\"),\n tags: tags\n },\n {\n name: \"count_ok\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"ok\"),\n tags: tags\n },\n {\n name: \"count_warning\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"warning\"),\n tags: tags\n },\n {\n name: \"count_critical\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"critical\"),\n tags: tags\n },\n {\n name: \"count_unknown\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"unknown\"),\n tags: tags\n }\n ]\n });\n\n if (!!args[\"set_metric_annotations\"]) {\n var i = 0;\n\n while(i < event.metrics.points.length) {\n event.annotations[\"io.sensu.bsm.selected_event_\" + event.metrics.points[i].name] = event.metrics.points[i].value.toString();\n i++;\n }\n }\n}\n\nif (!!args[\"critical_threshold\"] && percentOK <= args[\"critical_threshold\"]) {\n event.check.output = \"CRITICAL: Less than \" + args[\"critical_threshold\"].toString() + \"% of selected events are OK (\" + percentOK.toString() + \"%)\n\";\n event.check.status = 2;\n return event;\n}\n\nif (!!args[\"warning_threshold\"] && percentOK <= args[\"warning_threshold\"]) {\n event.check.output = \"WARNING: Less than \" + args[\"warning_threshold\"].toString() + \"% of selected events are OK (\" + percentOK.toString() + \"%)\n\";\n event.check.status = 1;\n return event;\n}\n\nif (!!args[\"critical_count\"]) {\n crit = sensu.CountBySeverity(\"critical\");\n\n if (crit >= args[\"critical_count\"]) {\n event.check.output = \"CRITICAL: \" + args[\"critical_count\"].toString() + \" or more selected events are in a critical state (\" + crit.toString() + \")\n\";\n event.check.status = 2;\n return event;\n }\n}\n\nif (!!args[\"warning_count\"]) {\n warn = sensu.CountBySeverity(\"warning\");\n\n if (warn >= args[\"warning_count\"]) {\n event.check.output = \"WARNING: \" + args[\"warning_count\"].toString() + \" or more selected events are in a warning state (\" + warn.toString() + \")\n\";\n event.check.status = 1;\n return event;\n }\n}\n\nevent.check.output = \"Everything looks good (\" + percentOK.toString() + \"% OK)\";\nevent.check.status = 0;\n\nreturn event;\n" + } +} +{{< /code >}} + +### API Specification + +/rule-templates/:rule-template (GET) | +---------------------|------ +description | Returns the specified rule template. +example url | http://hostname:8080/api/enterprise/bsm/v1/namespaces/default/rule-templates/aggregate +response type | Map +response codes |
    • **Success**: 200 (OK)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +{ + "type": "RuleTemplate", + "api_version": "bsm/v1", + "metadata": { + "name": "aggregate", + "namespace": "default", + "created_by": "admin" + }, + "spec": { + "arguments": { + "properties": { + "critical_count": { + "description": "create an event with a critical status if there the number of critical events is equal to or greater than this count", + "type": "number" + }, + "critical_threshold": { + "description": "create an event with a critical status if the percentage of non-zero events is equal to or greater than this threshold", + "type": "number" + }, + "metric_handlers": { + "default": {}, + "description": "metric handlers to use for produced metrics", + "items": { + "type": "string" + }, + "type": "array" + }, + "produce_metrics": { + "default": {}, + "description": "produce metrics from aggregate data and include them in the produced event", + "type": "boolean" + }, + "set_metric_annotations": { + "default": {}, + "description": "annotate the produced event with metric annotations", + "type": "boolean" + }, + "warning_count": { + "description": "create an event with a warning status if there the number of critical events is equal to or greater than this count", + "type": "number" + }, + "warning_threshold": { + "description": "create an event with a warning status if the percentage of non-zero events is equal to or greater than this threshold", + "type": "number" + } + }, + "required": null + }, + "description": "Monitor a distributed service - aggregate one or more events into a single event. This BSM rule template allows you to treat the results of multiple disparate check executions – executed across multiple disparate systems – as a single event. This template is extremely useful in dynamic environments and/or environments that have a reasonable tolerance for failure. Use this template when a service can be considered healthy as long as a minimum threshold is satisfied (for example, at least 5 healthy web servers? at least 70% of N processes healthy?).", + "eval": "\nif (events && events.length == 0) {\n event.check.output = \"WARNING: No events selected for aggregate\n\";\n event.check.status = 1;\n return event;\n}\n\nevent.annotations[\"io.sensu.bsm.selected_event_count\"] = events.length;\n\npercentOK = sensu.PercentageBySeverity(\"ok\");\n\nif (!!args[\"produce_metrics\"]) {\n var handlers = [];\n\n if (!!args[\"metric_handlers\"]) {\n handlers = args[\"metric_handlers\"].slice();\n }\n\n var ts = Math.floor(new Date().getTime() / 1000);\n\n event.timestamp = ts;\n\n var tags = [\n {\n name: \"service\",\n value: event.entity.name\n },\n {\n name: \"entity\",\n value: event.entity.name\n },\n {\n name: \"check\",\n value: event.check.name\n }\n ];\n\n event.metrics = sensu.NewMetrics({\n handlers: handlers,\n points: [\n {\n name: \"percent_non_zero\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"non-zero\"),\n tags: tags\n },\n {\n name: \"percent_ok\",\n timestamp: ts,\n value: percentOK,\n tags: tags\n },\n {\n name: \"percent_warning\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"warning\"),\n tags: tags\n },\n {\n name: \"percent_critical\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"critical\"),\n tags: tags\n },\n {\n name: \"percent_unknown\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"unknown\"),\n tags: tags\n },\n {\n name: \"count_non_zero\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"non-zero\"),\n tags: tags\n },\n {\n name: \"count_ok\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"ok\"),\n tags: tags\n },\n {\n name: \"count_warning\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"warning\"),\n tags: tags\n },\n {\n name: \"count_critical\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"critical\"),\n tags: tags\n },\n {\n name: \"count_unknown\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"unknown\"),\n tags: tags\n }\n ]\n });\n\n if (!!args[\"set_metric_annotations\"]) {\n var i = 0;\n\n while(i < event.metrics.points.length) {\n event.annotations[\"io.sensu.bsm.selected_event_\" + event.metrics.points[i].name] = event.metrics.points[i].value.toString();\n i++;\n }\n }\n}\n\nif (!!args[\"critical_threshold\"] && percentOK <= args[\"critical_threshold\"]) {\n event.check.output = \"CRITICAL: Less than \" + args[\"critical_threshold\"].toString() + \"% of selected events are OK (\" + percentOK.toString() + \"%)\n\";\n event.check.status = 2;\n return event;\n}\n\nif (!!args[\"warning_threshold\"] && percentOK <= args[\"warning_threshold\"]) {\n event.check.output = \"WARNING: Less than \" + args[\"warning_threshold\"].toString() + \"% of selected events are OK (\" + percentOK.toString() + \"%)\n\";\n event.check.status = 1;\n return event;\n}\n\nif (!!args[\"critical_count\"]) {\n crit = sensu.CountBySeverity(\"critical\");\n\n if (crit >= args[\"critical_count\"]) {\n event.check.output = \"CRITICAL: \" + args[\"critical_count\"].toString() + \" or more selected events are in a critical state (\" + crit.toString() + \")\n\";\n event.check.status = 2;\n return event;\n }\n}\n\nif (!!args[\"warning_count\"]) {\n warn = sensu.CountBySeverity(\"warning\");\n\n if (warn >= args[\"warning_count\"]) {\n event.check.output = \"WARNING: \" + args[\"warning_count\"].toString() + \" or more selected events are in a warning state (\" + warn.toString() + \")\n\";\n event.check.status = 1;\n return event;\n }\n}\n\nevent.check.output = \"Everything looks good (\" + percentOK.toString() + \"% OK)\";\nevent.check.status = 0;\n\nreturn event;\n" + } +} +{{< /code >}} + +## Create or update a rule template + +The `/rule-templates/:rule-template` API endpoint provides HTTP PUT access to create or update a specific rule template by name. + +### Example + +The following example demonstrates a request to the `/rule-templates/:rule-template` API endpoint to update the rule template `aggregate`: + +{{< code shell >}} +curl -X PUT \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "type": "RuleTemplate", + "api_version": "bsm/v1", + "metadata": { + "name": "aggregate" + }, + "spec": { + "arguments": { + "properties": { + "critical_count": { + "description": "create an event with a critical status if there the number of critical events is equal to or greater than this count", + "type": "number" + }, + "critical_threshold": { + "description": "create an event with a critical status if the percentage of non-zero events is equal to or greater than this threshold", + "type": "number" + }, + "metric_handlers": { + "default": {}, + "description": "metric handlers to use for produced metrics", + "items": { + "type": "string" + }, + "type": "array" + }, + "produce_metrics": { + "default": {}, + "description": "produce metrics from aggregate data and include them in the produced event", + "type": "boolean" + }, + "set_metric_annotations": { + "default": {}, + "description": "annotate the produced event with metric annotations", + "type": "boolean" + }, + "warning_count": { + "description": "create an event with a warning status if there the number of critical events is equal to or greater than this count", + "type": "number" + }, + "warning_threshold": { + "description": "create an event with a warning status if the percentage of non-zero events is equal to or greater than this threshold", + "type": "number" + } + }, + "required": null + }, + "description": "Monitor a distributed service - aggregate one or more events into a single event. This BSM rule template allows you to treat the results of multiple disparate check executions – executed across multiple disparate systems – as a single event. This template is extremely useful in dynamic environments and/or environments that have a reasonable tolerance for failure. Use this template when a service can be considered healthy as long as a minimum threshold is satisfied (for example, at least 5 healthy web servers? at least 70% of N processes healthy?).", + "eval": "\nif (events && events.length == 0) {\n event.check.output = \"WARNING: No events selected for aggregate\n\";\n event.check.status = 1;\n return event;\n}\n\nevent.annotations[\"io.sensu.bsm.selected_event_count\"] = events.length;\n\npercentOK = sensu.PercentageBySeverity(\"ok\");\n\nif (!!args[\"produce_metrics\"]) {\n var handlers = [];\n\n if (!!args[\"metric_handlers\"]) {\n handlers = args[\"metric_handlers\"].slice();\n }\n\n var ts = Math.floor(new Date().getTime() / 1000);\n\n event.timestamp = ts;\n\n var tags = [\n {\n name: \"service\",\n value: event.entity.name\n },\n {\n name: \"entity\",\n value: event.entity.name\n },\n {\n name: \"check\",\n value: event.check.name\n }\n ];\n\n event.metrics = sensu.NewMetrics({\n handlers: handlers,\n points: [\n {\n name: \"percent_non_zero\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"non-zero\"),\n tags: tags\n },\n {\n name: \"percent_ok\",\n timestamp: ts,\n value: percentOK,\n tags: tags\n },\n {\n name: \"percent_warning\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"warning\"),\n tags: tags\n },\n {\n name: \"percent_critical\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"critical\"),\n tags: tags\n },\n {\n name: \"percent_unknown\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"unknown\"),\n tags: tags\n },\n {\n name: \"count_non_zero\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"non-zero\"),\n tags: tags\n },\n {\n name: \"count_ok\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"ok\"),\n tags: tags\n },\n {\n name: \"count_warning\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"warning\"),\n tags: tags\n },\n {\n name: \"count_critical\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"critical\"),\n tags: tags\n },\n {\n name: \"count_unknown\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"unknown\"),\n tags: tags\n }\n ]\n });\n\n if (!!args[\"set_metric_annotations\"]) {\n var i = 0;\n\n while(i < event.metrics.points.length) {\n event.annotations[\"io.sensu.bsm.selected_event_\" + event.metrics.points[i].name] = event.metrics.points[i].value.toString();\n i++;\n }\n }\n}\n\nif (!!args[\"critical_threshold\"] && percentOK <= args[\"critical_threshold\"]) {\n event.check.output = \"CRITICAL: Less than \" + args[\"critical_threshold\"].toString() + \"% of selected events are OK (\" + percentOK.toString() + \"%)\n\";\n event.check.status = 2;\n return event;\n}\n\nif (!!args[\"warning_threshold\"] && percentOK <= args[\"warning_threshold\"]) {\n event.check.output = \"WARNING: Less than \" + args[\"warning_threshold\"].toString() + \"% of selected events are OK (\" + percentOK.toString() + \"%)\n\";\n event.check.status = 1;\n return event;\n}\n\nif (!!args[\"critical_count\"]) {\n crit = sensu.CountBySeverity(\"critical\");\n\n if (crit >= args[\"critical_count\"]) {\n event.check.output = \"CRITICAL: \" + args[\"critical_count\"].toString() + \" or more selected events are in a critical state (\" + crit.toString() + \")\n\";\n event.check.status = 2;\n return event;\n }\n}\n\nif (!!args[\"warning_count\"]) {\n warn = sensu.CountBySeverity(\"warning\");\n\n if (warn >= args[\"warning_count\"]) {\n event.check.output = \"WARNING: \" + args[\"warning_count\"].toString() + \" or more selected events are in a warning state (\" + warn.toString() + \")\n\";\n event.check.status = 1;\n return event;\n }\n}\n\nevent.check.output = \"Everything looks good (\" + percentOK.toString() + \"% OK)\";\nevent.check.status = 0;\n\nreturn event;\n" + } +}' \ +http://127.0.0.1:8080/api/enterprise/bsm/v1/namespaces/default/rule-templates/aggregate +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification + +/rule-templates/:rule-template (PUT) | +----------------|------ +description | Creates or updates the specified rule template. +example URL | http://hostname:8080/api/enterprise/bsm/v1/namespaces/default/rule-templates/aggregate +payload | {{< code json >}} +{ + "type": "RuleTemplate", + "api_version": "bsm/v1", + "metadata": { + "name": "aggregate" + }, + "spec": { + "arguments": { + "properties": { + "critical_count": { + "description": "create an event with a critical status if there the number of critical events is equal to or greater than this count", + "type": "number" + }, + "critical_threshold": { + "description": "create an event with a critical status if the percentage of non-zero events is equal to or greater than this threshold", + "type": "number" + }, + "metric_handlers": { + "default": {}, + "description": "metric handlers to use for produced metrics", + "items": { + "type": "string" + }, + "type": "array" + }, + "produce_metrics": { + "default": {}, + "description": "produce metrics from aggregate data and include them in the produced event", + "type": "boolean" + }, + "set_metric_annotations": { + "default": {}, + "description": "annotate the produced event with metric annotations", + "type": "boolean" + }, + "warning_count": { + "description": "create an event with a warning status if there the number of critical events is equal to or greater than this count", + "type": "number" + }, + "warning_threshold": { + "description": "create an event with a warning status if the percentage of non-zero events is equal to or greater than this threshold", + "type": "number" + } + }, + "required": null + }, + "description": "Monitor a distributed service - aggregate one or more events into a single event. This BSM rule template allows you to treat the results of multiple disparate check executions – executed across multiple disparate systems – as a single event. This template is extremely useful in dynamic environments and/or environments that have a reasonable tolerance for failure. Use this template when a service can be considered healthy as long as a minimum threshold is satisfied (for example, at least 5 healthy web servers? at least 70% of N processes healthy?).", + "eval": "\nif (events && events.length == 0) {\n event.check.output = \"WARNING: No events selected for aggregate\n\";\n event.check.status = 1;\n return event;\n}\n\nevent.annotations[\"io.sensu.bsm.selected_event_count\"] = events.length;\n\npercentOK = sensu.PercentageBySeverity(\"ok\");\n\nif (!!args[\"produce_metrics\"]) {\n var handlers = [];\n\n if (!!args[\"metric_handlers\"]) {\n handlers = args[\"metric_handlers\"].slice();\n }\n\n var ts = Math.floor(new Date().getTime() / 1000);\n\n event.timestamp = ts;\n\n var tags = [\n {\n name: \"service\",\n value: event.entity.name\n },\n {\n name: \"entity\",\n value: event.entity.name\n },\n {\n name: \"check\",\n value: event.check.name\n }\n ];\n\n event.metrics = sensu.NewMetrics({\n handlers: handlers,\n points: [\n {\n name: \"percent_non_zero\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"non-zero\"),\n tags: tags\n },\n {\n name: \"percent_ok\",\n timestamp: ts,\n value: percentOK,\n tags: tags\n },\n {\n name: \"percent_warning\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"warning\"),\n tags: tags\n },\n {\n name: \"percent_critical\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"critical\"),\n tags: tags\n },\n {\n name: \"percent_unknown\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"unknown\"),\n tags: tags\n },\n {\n name: \"count_non_zero\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"non-zero\"),\n tags: tags\n },\n {\n name: \"count_ok\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"ok\"),\n tags: tags\n },\n {\n name: \"count_warning\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"warning\"),\n tags: tags\n },\n {\n name: \"count_critical\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"critical\"),\n tags: tags\n },\n {\n name: \"count_unknown\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"unknown\"),\n tags: tags\n }\n ]\n });\n\n if (!!args[\"set_metric_annotations\"]) {\n var i = 0;\n\n while(i < event.metrics.points.length) {\n event.annotations[\"io.sensu.bsm.selected_event_\" + event.metrics.points[i].name] = event.metrics.points[i].value.toString();\n i++;\n }\n }\n}\n\nif (!!args[\"critical_threshold\"] && percentOK <= args[\"critical_threshold\"]) {\n event.check.output = \"CRITICAL: Less than \" + args[\"critical_threshold\"].toString() + \"% of selected events are OK (\" + percentOK.toString() + \"%)\n\";\n event.check.status = 2;\n return event;\n}\n\nif (!!args[\"warning_threshold\"] && percentOK <= args[\"warning_threshold\"]) {\n event.check.output = \"WARNING: Less than \" + args[\"warning_threshold\"].toString() + \"% of selected events are OK (\" + percentOK.toString() + \"%)\n\";\n event.check.status = 1;\n return event;\n}\n\nif (!!args[\"critical_count\"]) {\n crit = sensu.CountBySeverity(\"critical\");\n\n if (crit >= args[\"critical_count\"]) {\n event.check.output = \"CRITICAL: \" + args[\"critical_count\"].toString() + \" or more selected events are in a critical state (\" + crit.toString() + \")\n\";\n event.check.status = 2;\n return event;\n }\n}\n\nif (!!args[\"warning_count\"]) {\n warn = sensu.CountBySeverity(\"warning\");\n\n if (warn >= args[\"warning_count\"]) {\n event.check.output = \"WARNING: \" + args[\"warning_count\"].toString() + \" or more selected events are in a warning state (\" + warn.toString() + \")\n\";\n event.check.status = 1;\n return event;\n }\n}\n\nevent.check.output = \"Everything looks good (\" + percentOK.toString() + \"% OK)\";\nevent.check.status = 0;\n\nreturn event;\n" + } +} +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Delete a rule template + +The `/rule-templates/:rule-template` API endpoint provides HTTP DELETE access to delete the specified rule template from Sensu. + +### Example + +The following example shows a request to the `/rule-templates/:rule-template` API endpoint to delete the rule template `aggregate`, resulting in a successful `HTTP/1.1 204 No Content` response. + +{{< code shell >}} +curl -X DELETE \ +-H "Authorization: Key $SENSU_API_KEY" \ +http://127.0.0.1:8080/api/enterprise/bsm/v1/namespaces/default/rule-templates/aggregate +{{< /code >}} + +### API Specification + +/rule-templates/:rule-template (DELETE) | +--------------------------|------ +description | Deletes the specified rule template from Sensu. +example url | http://hostname:8080/api/enterprise/bsm/v1/rule-templates/aggregate +response codes |
    • **Success**: 204 (No Content)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + + +[1]: ../../../observability-pipeline/observe-schedule/service-components/ +[2]: ../../../observability-pipeline/observe-schedule/rule-templates/ diff --git a/content/sensu-go/6.12/api/enterprise/datastore.md b/content/sensu-go/6.12/api/enterprise/datastore.md new file mode 100644 index 0000000000..f5ee5067ab --- /dev/null +++ b/content/sensu-go/6.12/api/enterprise/datastore.md @@ -0,0 +1,242 @@ +--- +title: "enterprise/store/v1" +description: "Read this API documentation for information about Sensu enterprise/store/v1 API endpoints, with examples for retrieving and managing provider definitions." +enterprise_api_title: "enterprise/store/v1" +type: "enterprise_api" +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: enterprise +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access the datastore feature in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} + +{{% notice note %}} +**NOTE**: Requests to `enterprise/store/v1` API endpoints require you to authenticate with a Sensu [API key](../../#configure-an-environment-variable-for-api-key-authentication) or [access token](../../#authenticate-with-auth-api-endpoints). +The code examples in this document use the [environment variable](../../#configure-an-environment-variable-for-api-key-authentication) `$SENSU_API_KEY` to represent a valid API key in API requests. +{{% /notice %}} + +## Get all datastore providers {#provider-get} + +The `/provider` API endpoint provides HTTP GET access to [Sensu datastore][1] data. + +### Example {#provider-get-example} + +The following example demonstrates a GET request to the `/provider` API endpoint, resulting in a JSON map that contains a list of Sensu datastore providers. + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/enterprise/store/v1/provider +-H "Authorization: Key $SENSU_API_KEY" \ +{{< /code >}} + +The request results in a successful `HTTP/1.1 200 OK` response and a JSON array that contains the [datastore provider definitions][1]: + +{{< code text >}} +[ + { + "type": "PostgresConfig", + "api_version": "store/v1", + "metadata": { + "name": "my-postgres", + "created_by": "admin" + }, + "spec": { + "dsn": "postgresql://user:secret@host:port/dbname", + "max_conn_lifetime": "5m", + "max_idle_conns": 2, + "pool_size": 20, + "strict": true, + "enable_round_robin": true + } + } +] +{{< /code >}} + +### API Specification {#provider-get-specification} + +/provider (GET) | +---------------|------ +description | Returns the list of datastore providers. +example url | http://hostname:8080/api/enterprise/store/v1/provider +response type | Map +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code json >}} +[ + { + "type": "PostgresConfig", + "api_version": "store/v1", + "metadata": { + "name": "my-postgres", + "created_by": "admin" + }, + "spec": { + "dsn": "postgresql://user:secret@host:port/dbname", + "max_conn_lifetime": "5m", + "max_idle_conns": 2, + "pool_size": 20, + "strict": true, + "enable_round_robin": true + } + } +] +{{< /code >}} + +## Get a specific datastore provider {#providerprovider-get} + +The `/provider/:provider` API endpoint provides HTTP GET access to retrieve a Sensu datastore provider. + +### Example {#providerprovider-get-example} + +The following example queries the `/provider/:provider` API endpoint for a specific `:provider`: + +{{< code shell >}} +curl -X GET \ +-H "Authorization: Key $SENSU_API_KEY" \ +http://127.0.0.1:8080/api/enterprise/store/v1/provider/my-postgres +{{< /code >}} + +The request will return a successful `HTTP/1.1 200 OK` response and a JSON map that contains the requested [`:provider` definition][1] (in this example, `my-postgres`): + +{{< code text >}} +{ + "type": "PostgresConfig", + "api_version": "store/v1", + "metadata": { + "name": "my-postgres", + "created_by": "admin" + }, + "spec": { + "batch_buffer": 0, + "batch_size": 1, + "batch_workers": 0, + "dsn": "postgresql://user:secret@host:port/dbname", + "max_conn_lifetime": "5m", + "max_idle_conns": 2, + "pool_size": 20, + "strict": true, + "enable_round_robin": true + } +} +{{< /code >}} + +### API Specification {#providerprovider-get-specification} + +/provider/:provider (GET) | +----------------|------ +description | Returns the specified datastore provider. +example url | http://hostname:8080/api/enterprise/store/v1/provider/my-postgres +url parameters | Required: `my-postgres` (name of provider to retrieve). +response codes |
    • **Success**: 200 (OK)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +{ + "type": "PostgresConfig", + "api_version": "store/v1", + "metadata": { + "name": "my-postgres", + "created_by": "admin" + }, + "spec": { + "batch_buffer": 0, + "batch_size": 1, + "batch_workers": 0, + "dsn": "postgresql://user:secret@host:port/dbname", + "max_conn_lifetime": "5m", + "max_idle_conns": 2, + "pool_size": 20, + "strict": true, + "enable_round_robin": true + } +} +{{< /code >}} + +## Create or update a datastore provider {#providerprovider-put} + +The `/provider/:provider` API endpoint provides HTTP PUT access to create or update a Sensu datastore provider. + +### Example {#providerprovider-put-example} + +{{< code shell >}} +curl -X PUT \ +http://127.0.0.1:8080/api/enterprise/store/v1/provider/my-postgres \ +-H "Authorization: Key $SENSU_API_KEY" \ +-d '{ + "type": "PostgresConfig", + "api_version": "store/v1", + "metadata": { + "name": "my-postgres" + }, + "spec": { + "batch_buffer": 0, + "batch_size": 1, + "batch_workers": 0, + "dsn": "postgresql://user:secret@host:port/dbname", + "max_conn_lifetime": "5m", + "max_idle_conns": 2, + "pool_size": 20, + "strict": true, + "enable_round_robin": true + } +}' +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#providerprovider-put-specification} + +/provider/:provider (PUT) | +----------------|------ +description | Creates a datastore provider. +example url | http://hostname:8080/api/enterprise/store/v1/provider/my-postgres +url parameters | Required: `my-postgres` (name to use for provider). +payload | {{< code shell >}} +{ + "type": "PostgresConfig", + "api_version": "store/v1", + "metadata": { + "name": "my-postgres" + }, + "spec": { + "batch_buffer": 0, + "batch_size": 1, + "batch_workers": 0, + "dsn": "postgresql://user:secret@host:port/dbname", + "max_conn_lifetime": "5m", + "max_idle_conns": 2, + "pool_size": 20, + "strict": true, + "enable_round_robin": true + } +} +{{< /code >}} +response codes |
    • **Success**: 200 (OK)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + +## Delete a datastore provider {#providerprovider-delete} + +The `/provider/:provider` API endpoint provides HTTP DELETE access to remove a Sensu datastore provider. + +### Example {#providerprovider-delete-example} + +The following example shows a request to the `/provider/:provider` API endpoint to remove the Sensu datastore provider with the ID `my-postgres`, resulting in a successful `HTTP/1.1 204 No Content` response. + +{{< code shell >}} +curl -X DELETE \ +-H "Authorization: Key $SENSU_API_KEY" \ +http://127.0.0.1:8080/api/enterprise/store/v1/provider/my-postgres +{{< /code >}} + +### API Specification {#providerprovider-delete-specification} + +/provider/:provider (DELETE) | +--------------------------|------ +description | Removes the specified datastore provider. +example url | http://hostname:8080/api/enterprise/store/v1/provider/my-postgres +url parameters | Required: `my-postgres` (name of provider to delete). +response codes |
    • **Success**: 204 (No Content)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + + +[1]: ../../../operations/deploy-sensu/datastore/ diff --git a/content/sensu-go/6.12/api/enterprise/federation.md b/content/sensu-go/6.12/api/enterprise/federation.md new file mode 100644 index 0000000000..b706bb9712 --- /dev/null +++ b/content/sensu-go/6.12/api/enterprise/federation.md @@ -0,0 +1,526 @@ +--- +title: "enterprise/federation/v1" +description: "Read this API documentation for information about Sensu enterprise/federation/v1 API endpoints, wich allow you to control federation of Sensu clusters." +enterprise_api_title: "enterprise/federation/v1" +type: "enterprise_api" +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: enterprise +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access federation in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} + +{{% notice note %}} +**NOTE**: Requests to `enterprise/federation/v1` API endpoints require you to authenticate with a Sensu [API key](../../#configure-an-environment-variable-for-api-key-authentication) or [access token](../../#authenticate-with-auth-api-endpoints). +The code examples in this document use the [environment variable](../../#configure-an-environment-variable-for-api-key-authentication) `$SENSU_API_KEY` to represent a valid API key in API requests. +{{% /notice %}} + +## Get all replicators + +The `/etcd-replicators` API endpoint provides HTTP GET access to a list of replicators. + +{{% notice note %}} +**NOTE**: The etcd-replicators datatype is only accessible for users who have a cluster role that permits access to replication resources. +{{% /notice %}} + +### Example {#etcd-replicators-get-example} + +The following example demonstrates a GET request to the `/etcd-replicators` API endpoint: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/enterprise/federation/v1/etcd-replicators \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request results in a successful `HTTP/1.1 200 OK` response and a JSON array that contains the [etcd replicator definitions][1]: + +{{< code text >}} +[ + { + "api_version": "federation/v1", + "type": "EtcdReplicator", + "metadata": { + "name": "my_replicator", + "created_by": "admin" + }, + "spec": { + "ca_cert": "/path/to/ssl/trusted-certificate-authorities.pem", + "cert": "/path/to/ssl/cert.pem", + "key": "/path/to/ssl/key.pem", + "insecure": false, + "url": "http://remote-etcd.example.com:2379", + "api_version": "core/v2", + "resource": "Role", + "replication_interval_seconds": 30 + } + } +] +{{< /code >}} + +### API Specification {#etcd-replicators-get-specification} + +/etcd-replicators (GET) | +---------------|------ +description | Returns the list of replicators. +example url | http://hostname:8080/api/enterprise/federation/v1/etcd-replicators +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "api_version": "federation/v1", + "type": "EtcdReplicator", + "metadata": { + "name": "my_replicator", + "created_by": "admin" + }, + "spec": { + "ca_cert": "/path/to/ssl/trusted-certificate-authorities.pem", + "cert": "/path/to/ssl/cert.pem", + "key": "/path/to/ssl/key.pem", + "insecure": false, + "url": "http://remote-etcd.example.com:2379", + "api_version": "core/v2", + "resource": "Role", + "replication_interval_seconds": 30 + } + } +] +{{< /code >}} + +## Create a new replicator + +The `/etcd-replicators` API endpoint provides HTTP POST access to create replicators. + +{{% notice note %}} +**NOTE**: Create a replicator for each resource type you want to replicate. +Replicating `namespace` resources will **not** replicate the resources that belong to those namespaces. +{{% /notice %}} + +### Example {#etcd-replicators-post-example} + +The following example demonstrates a request to the `/etcd-replicators` API endpoint to create the replicator `my_replicator`: + +{{< code shell >}} +curl -X POST \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "api_version": "federation/v1", + "type": "EtcdReplicator", + "metadata": { + "name": "my_replicator" + }, + "spec": { + "ca_cert": "/path/to/ssl/trusted-certificate-authorities.pem", + "cert": "/path/to/ssl/cert.pem", + "key": "/path/to/ssl/key.pem", + "insecure": false, + "url": "http://remote-etcd.example.com:2379", + "api_version": "core/v2", + "resource": "Role", + "replication_interval_seconds": 30 + } +}' \ +http://127.0.0.1:8080/api/enterprise/federation/v1/etcd-replicators +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#etcd-replicators-post-specification} + +/etcd-replicators (POST) | +----------------|------ +description | Creates a new replicator (if none exists). +example URL | http://hostname:8080/api/enterprise/federation/v1/etcd-replicators +payload | {{< code shell >}} +{ + "api_version": "federation/v1", + "type": "EtcdReplicator", + "metadata": { + "name": "my_replicator" + }, + "spec": { + "ca_cert": "/path/to/ssl/trusted-certificate-authorities.pem", + "cert": "/path/to/ssl/cert.pem", + "key": "/path/to/ssl/key.pem", + "insecure": false, + "url": "http://remote-etcd.example.com:2379", + "api_version": "core/v2", + "resource": "Role", + "replication_interval_seconds": 30 + } +} +{{< /code >}} +response codes |
    • **Success**: 200 (OK)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Get a specific replicator {#etcd-replicatorsetcd-replicator-get} + +The `/etcd-replicators/:etcd-replicator` API endpoint provides HTTP GET access to data for a specific `:etcd-replicator`, by replicator name. + +{{% notice note %}} +**NOTE**: The etcd-replicators datatype is only accessible for users who have a cluster role that permits access to replication resources. +{{% /notice %}} + +### Example {#etcd-replicatorsetcd-replicator-get-example} + +The following example queries the `/etcd-replicators/:etcd-replicator` API endpoint for a specific `:etcd-replicator`. + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/enterprise/federation/v1/etcd-replicators/my_replicator \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request will return a successful `HTTP/1.1 200 OK` response and a JSON map that contains the requested [`:etcd-replicator` definition][1] (in this example, `my_replicator`): + +{{< code text >}} +{ + "api_version": "federation/v1", + "type": "EtcdReplicator", + "metadata": { + "name": "my_replicator", + "created_by": "admin" + }, + "spec": { + "ca_cert": "/path/to/ssl/trusted-certificate-authorities.pem", + "cert": "/path/to/ssl/cert.pem", + "key": "/path/to/ssl/key.pem", + "insecure": false, + "url": "http://remote-etcd.example.com:2379", + "api_version": "core/v2", + "resource": "Role", + "replication_interval_seconds": 30 + } +} +{{< /code >}} + +### API Specification {#etcd-replicatorsetcd-replicator-get-specification} + +/etcd-replicators/:etcd-replicator (GET) | +---------------------|------ +description | Returns the specified replicator. +example url | http://hostname:8080/api/enterprise/federation/v1/etcd-replicators/my_replicator +response type | Map +response codes |
    • **Success**: 200 (OK)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +{ + "api_version": "federation/v1", + "type": "EtcdReplicator", + "metadata": { + "name": "my_replicator", + "created_by": "admin" + }, + "spec": { + "ca_cert": "/path/to/ssl/trusted-certificate-authorities.pem", + "cert": "/path/to/ssl/cert.pem", + "key": "/path/to/ssl/key.pem", + "insecure": false, + "url": "http://remote-etcd.example.com:2379", + "api_version": "core/v2", + "resource": "Role", + "replication_interval_seconds": 30 + } +} +{{< /code >}} + +## Create or update a replicator {#etcd-replicatorsetcd-replicator-put} + +The `/etcd-replicators/:etcd-replicator` API endpoint provides HTTP PUT access to create or update a specific `:etcd-replicator`, by replicator name. + +### Example {#etcd-replicatorsetcd-replicator-put-example} + +The following example demonstrates a request to the `/etcd-replicators/:etcd-replicator` API endpoint to update the replicator `my_replicator`: + +{{< code shell >}} +curl -X PUT \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "api_version": "federation/v1", + "type": "EtcdReplicator", + "metadata": { + "name": "my_replicator" + }, + "spec": { + "ca_cert": "/path/to/ssl/trusted-certificate-authorities.pem", + "cert": "/path/to/ssl/cert.pem", + "key": "/path/to/ssl/key.pem", + "insecure": false, + "url": "http://remote-etcd.example.com:2379", + "api_version": "core/v2", + "resource": "Role", + "replication_interval_seconds": 30 + } +}' \ +http://127.0.0.1:8080/api/enterprise/federation/v1/etcd-replicators/my-replicator +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#etcd-replicatorsetcd-replicator-put-specification} + +/etcd-replicators/:etcd-replicator (PUT) | +----------------|------ +description | Creates or updates the specified replicator. The replicator resource and API version cannot be altered. +example URL | http://hostname:8080/api/enterprise/federation/v1/etcd-replicators/my_replicator +payload | {{< code json >}} +{ + "api_version": "federation/v1", + "type": "EtcdReplicator", + "metadata": { + "name": "my_replicator" + }, + "spec": { + "ca_cert": "/path/to/ssl/trusted-certificate-authorities.pem", + "cert": "/path/to/ssl/cert.pem", + "key": "/path/to/ssl/key.pem", + "insecure": false, + "url": "http://remote-etcd.example.com:2379", + "api_version": "core/v2", + "resource": "Role", + "replication_interval_seconds": 30 + } +} +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Delete a replicator {#etcd-replicatorsetcd-replicator-delete} + +The `/etcd-replicators/:etcd-replicator` API endpoint provides HTTP DELETE access to delete the specified replicator from Sensu. + +### Example {#etcd-replicatorsetcd-replicator-delete-example} + +The following example shows a request to the `/etcd-replicators/:etcd-replicator` API endpoint to delete the replicator `my_replicator`, resulting in a successful `HTTP/1.1 204 No Content` response. + +{{< code shell >}} +curl -X DELETE \ +-H "Authorization: Key $SENSU_API_KEY" \ +http://127.0.0.1:8080/api/enterprise/federation/v1/etcd-replicators/my_replicator +{{< /code >}} + +### API Specification {#etcd-replicatorsetcd-replicator-delete-specification} + +/etcd-replicators/:etcd-replicator (DELETE) | +--------------------------|------ +description | Deletes the specified replicator from Sensu. +example url | http://hostname:8080/api/enterprise/federation/v1/etcd-replicators/my_replicator +response codes |
    • **Success**: 204 (No Content)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + +## Get all clusters + +The `/clusters` API endpoint provides HTTP GET access to a list of clusters. + +### Example {#clusters-get-example} + +The following example demonstrates a request to the `/clusters` API endpoint, resulting in a list of clusters. + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/enterprise/federation/v1/clusters \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request results in a successful `HTTP/1.1 200 OK` response and a JSON array that contains the cluster definitions: + +{{< code text >}} +[ + { + "type": "Cluster", + "api_version": "federation/v1", + "metadata": { + "name": "us-west-2a", + "created_by": "admin" + }, + "spec": { + "api_urls": [ + "http://10.0.0.1:8080", + "http://10.0.0.2:8080", + "http://10.0.0.3:8080" + ] + } + } +] +{{< /code >}} + +### API Specification {#clusters-get-specification} + +/clusters (GET) | +---------------|------ +description | Returns the list of clusters. +example url | http://hostname:8080/api/enterprise/federation/v1/clusters +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "type": "Cluster", + "api_version": "federation/v1", + "metadata": { + "name": "us-west-2a", + "created_by": "admin" + }, + "spec": { + "api_urls": [ + "http://10.0.0.1:8080", + "http://10.0.0.2:8080", + "http://10.0.0.3:8080" + ] + } + } +] +{{< /code >}} + +## Get a specific cluster {#clusterscluster-get} + +The `/clusters/:cluster` API endpoint provides HTTP GET access to data for a specific `cluster`, by cluster name. + +### Example {#clusterscluster-get-example} + +The following example queries the `/clusters/:cluster` API endpoint for a specific `:cluster`. + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/enterprise/federation/v1/clusters/us-west-2a \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request will return a successful `HTTP/1.1 200 OK` response and a JSON map that contains the requested `:cluster` definition (in this example, `us-west-2a`): + +{{< code text >}} +{ + "type": "Cluster", + "api_version": "federation/v1", + "metadata": { + "name": "us-west-2a", + "created_by": "admin" + }, + "spec": { + "api_urls": [ + "http://10.0.0.1:8080", + "http://10.0.0.2:8080", + "http://10.0.0.3:8080" + ] + } +} +{{< /code >}} + +### API Specification {#clusterscluster-get-specification} + +/clusters/:cluster (GET) | +---------------------|------ +description | Returns the specified cluster. +example url | http://hostname:8080/api/enterprise/federation/v1/clusters/us-west-2a +response type | Map +response codes |
    • **Success**: 200 (OK)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +{ + "type": "Cluster", + "api_version": "federation/v1", + "metadata": { + "name": "us-west-2a", + "created_by": "admin" + }, + "spec": { + "api_urls": [ + "http://10.0.0.1:8080", + "http://10.0.0.2:8080", + "http://10.0.0.3:8080" + ] + } +} +{{< /code >}} + +## Create or update a cluster {#clusterscluster-put} + +The `/clusters/:cluster` API endpoint provides HTTP PUT access to create or update a specific `cluster`, by cluster name. + +{{% notice note %}} +**NOTE**: Only cluster admins have PUT access to clusters. +{{% /notice %}} + +### Example {#clusterscluster-put-example} + +The following example demonstrates a request to the `/clusters/:cluster` API endpoint to update the cluster `us-west-2a`: + +{{< code shell >}} +curl -X PUT \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "type": "Cluster", + "api_version": "federation/v1", + "metadata": { + "name": "us-west-2a" + }, + "spec": { + "api_urls": [ + "http://10.0.0.1:8080", + "http://10.0.0.2:8080", + "http://10.0.0.3:8080" + ] + } +}' \ +http://127.0.0.1:8080/api/enterprise/federation/v1/clusters/us-west-2a +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#clusterscluster-put-specification} + +/clusters/:cluster (PUT) | +----------------|------ +description | Creates or updates the specified cluster. +example URL | http://hostname:8080/api/enterprise/federation/v1/clusters/us-west-2a +payload | {{< code shell >}} +{ + "type": "Cluster", + "api_version": "federation/v1", + "metadata": { + "name": "us-west-2a" + }, + "spec": { + "api_urls": [ + "http://10.0.0.1:8080", + "http://10.0.0.2:8080", + "http://10.0.0.3:8080" + ] + } +} +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Delete a cluster {#clusterscluster-delete} + +The `/clusters/:cluster` API endpoint provides HTTP DELETE access to delete the specified cluster from Sensu. + +{{% notice note %}} +**NOTE**: Only cluster admins have DELETE access to clusters. +{{% /notice %}} + +### Example {#clusterscluster-delete-example} + +The following example shows a request to the `/clusters/:cluster` API endpoint to delete the cluster `us-west-2a`, resulting in a successful `HTTP/1.1 204 No Content` response. + +{{< code shell >}} +curl -X DELETE \ +-H "Authorization: Key $SENSU_API_KEY" \ +http://127.0.0.1:8080/api/enterprise/federation/v1/clusters/us-west-2a +{{< /code >}} + +### API Specification {#clusterscluster-delete-specification} + +/clusters/:cluster (DELETE) | +--------------------------|------ +description | Deletes the specified cluster from Sensu. +example url | http://hostname:8080/api/enterprise/federation/v1/clusters/us-west-2a +response codes |
    • **Success**: 204 (No Content)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + + +[1]: ../../../operations/deploy-sensu/etcdreplicators/ diff --git a/content/sensu-go/6.12/api/enterprise/pipeline.md b/content/sensu-go/6.12/api/enterprise/pipeline.md new file mode 100644 index 0000000000..1504d63b67 --- /dev/null +++ b/content/sensu-go/6.12/api/enterprise/pipeline.md @@ -0,0 +1,669 @@ +--- +title: "enterprise/pipeline/v1" +description: "Read this API documentation for information about Sensu enterprise/pipeline/v1 API endpoints, with examples for retrieving and managing pipeline resources." +enterprise_api_title: "enterprise/pipeline/v1" +type: "enterprise_api" +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: enterprise +--- + +{{% notice warning %}} +**IMPORTANT**: The `enterprise/pipeline/v1` API endpoints do not allow you to create and manage [pipelines](../../../observability-pipeline/observe-process/pipelines/), which are composed of observation event processing workflows. +Instead, `enterprise/pipeline/v1` API endpoints allow you to create and manage resources that can **only** be used within pipelines (the [Sumo Logic metrics handlers](../../../observability-pipeline/observe-process/sumo-logic-metrics-handlers) and [TCP stream handlers](../../../observability-pipeline/observe-process/tcp-stream-handlers)). +{{% /notice %}} + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access `enterprise/pipeline/v1` API endpoints in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} + +{{% notice note %}} +**NOTE**: Requests to `enterprise/pipeline/v1` endpoints require you to authenticate with a Sensu [API key](../../#configure-an-environment-variable-for-api-key-authentication) or [access token](../../#authenticate-with-auth-api-endpoints). +The code examples in this document use the [environment variable](../../#configure-an-environment-variable-for-api-key-authentication) `$SENSU_API_KEY` to represent a valid API key in API requests. +{{% /notice %}} + +## Get all Sumo Logic metrics handler resources + +The `/sumo-logic-metrics-handlers` API endpoint provides HTTP GET access to [Sumo Logic metrics handler][5] data. + +### Example {#handlers-get-example} + +The following example demonstrates a GET request to the `/sumo-logic-metrics-handlers` API endpoint: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/enterprise/pipeline/v1/namespaces/default/sumo-logic-metrics-handlers \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request results in a successful `HTTP/1.1 200 OK` response and a JSON array that contains the [Sumo Logic metrics handler definitions][5] in the `default` namespace: + +{{< code text >}} +[ + { + "type": "SumoLogicMetricsHandler", + "api_version": "pipeline/v1", + "metadata": { + "name": "sumologic_http_log_metrics_us1", + "namespace": "default" + }, + "spec": { + "url": "$SUMO_LOGIC_SOURCE_URL", + "secrets": [ + { + "name": "SUMO_LOGIC_SOURCE_URL", + "secret": "sumologic_metrics_us1" + } + ], + "max_connections": 10, + "timeout": "30s" + } + }, + { + "type": "SumoLogicMetricsHandler", + "api_version": "pipeline/v1", + "metadata": { + "name": "sumologic_http_log_metrics_us2", + "namespace": "default" + }, + "spec": { + "url": "$SUMO_LOGIC_SOURCE_URL", + "secrets": [ + { + "name": "SUMO_LOGIC_SOURCE_URL", + "secret": "sumologic_metrics_us2" + } + ], + "max_connections": 10, + "timeout": "30s" + } + } +] +{{< /code >}} + +### API Specification {#handlers-get-specification} + +/sumo-logic-metrics-handlers (GET) | +---------------|------ +description | Returns the list of Sumo Logic metrics handlers. +example url | http://hostname:8080/api/enterprise/pipeline/v1/namespaces/default/sumo-logic-metrics-handlers +pagination | This endpoint supports [pagination][2] using the `limit` and `continue` query parameters. +response filtering | This endpoint supports [API response filtering][3]. +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "type": "SumoLogicMetricsHandler", + "api_version": "pipeline/v1", + "metadata": { + "name": "sumologic_http_log_metrics_us1", + "namespace": "default" + }, + "spec": { + "url": "$SUMO_LOGIC_SOURCE_URL", + "secrets": [ + { + "name": "SUMO_LOGIC_SOURCE_URL", + "secret": "sumologic_metrics_us1" + } + ], + "max_connections": 10, + "timeout": "30s" + } + }, + { + "type": "SumoLogicMetricsHandler", + "api_version": "pipeline/v1", + "metadata": { + "name": "sumologic_http_log_metrics_us2", + "namespace": "default" + }, + "spec": { + "url": "$SUMO_LOGIC_SOURCE_URL", + "secrets": [ + { + "name": "SUMO_LOGIC_SOURCE_URL", + "secret": "sumologic_metrics_us2" + } + ], + "max_connections": 10, + "timeout": "30s" + } + } +] +{{< /code >}} + +## Create a new Sumo Logic metrics handler + +The `/sumo-logic-metrics-handlers` API endpoint provides HTTP POST access to create a Sumo Logic metrics handler. + +### Example {#handlers-post-example} + +In the following example, an HTTP POST request is submitted to the `/sumo-logic-metrics-handlers` API endpoint to create the Sumo Logic metrics handler `sumologic_http_log_metrics_us1`: + +{{< code shell >}} +curl -X POST \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "type": "SumoLogicMetricsHandler", + "api_version": "pipeline/v1", + "metadata": { + "name": "sumologic_http_log_metrics_us1" + }, + "spec": { + "url": "$SUMO_LOGIC_SOURCE_URL", + "secrets": [ + { + "name": "SUMO_LOGIC_SOURCE_URL", + "secret": "sumologic_metrics_us1" + } + ], + "max_connections": 10, + "timeout": "30s" + } +}' \ +http://127.0.0.1:8080/api/enterprise/pipeline/v1/namespaces/default/sumo-logic-metrics-handlers +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#handlers-post-specification} + +/sumo-logic-metrics-handlers (POST) | +----------------|------ +description | Creates a Sensu Sumo Logic metrics handler. +example URL | http://hostname:8080/api/enterprise/pipeline/v1/namespaces/default/sumo-logic-metrics-handlers +payload | {{< code shell >}} +{ + "type": "SumoLogicMetricsHandler", + "api_version": "pipeline/v1", + "metadata": { + "name": "sumologic_http_log_metrics_us1" + }, + "spec": { + "url": "$SUMO_LOGIC_SOURCE_URL", + "secrets": [ + { + "name": "SUMO_LOGIC_SOURCE_URL", + "secret": "sumologic_metrics_us1" + } + ], + "max_connections": 10, + "timeout": "30s" + } +} +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Get a specific Sumo Logic metrics handler + +The `/sumo-logic-metrics-handlers/:sumo-logic-metrics-handler` API endpoint provides HTTP GET access to [Sumo Logic metrics handler data][5] for specific `:sumo-logic-metrics-handler` definitions, by handler `name`. + +### Example + +The following example queries the `/sumo-logic-metrics-handlers/:sumo-logic-metrics-handler` API endpoint for the `:sumo-logic-metrics-handler` named `sumologic_http_log_metrics_us1`: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/enterprise/pipeline/v1/namespaces/default/sumo-logic-metrics-handlers/sumologic_http_log_metrics_us1 \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request will return a successful `HTTP/1.1 200 OK` response and a JSON map that contains the requested [`:sumo-logic-metrics-handler` definition][5] (in this example, `sumologic_http_log_metrics_us1`): + +{{< code text >}} +{ + "type": "SumoLogicMetricsHandler", + "api_version": "pipeline/v1", + "metadata": { + "name": "sumologic_http_log_metrics_us1", + "namespace": "default" + }, + "spec": { + "url": "$SUMO_LOGIC_SOURCE_URL", + "secrets": [ + { + "name": "SUMO_LOGIC_SOURCE_URL", + "secret": "sumologic_metrics_us1" + } + ], + "max_connections": 10, + "timeout": "30s" + } +} +{{< /code >}} + +### API Specification + +/sumo-logic-metrics-handlers/:sumo-logic-metrics-handler (GET) | +---------------------|------ +description | Returns a Sumo Logic metrics handler. +example url | http://hostname:8080/api/enterprise/pipeline/v1/namespaces/default/sumo-logic-metrics-handlers/sumologic_http_log_metrics_us1 +response type | Map +response codes |
    • **Success**: 200 (OK)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +{ + "type": "SumoLogicMetricsHandler", + "api_version": "pipeline/v1", + "metadata": { + "name": "sumologic_http_log_metrics_us1", + "namespace": "default" + }, + "spec": { + "url": "$SUMO_LOGIC_SOURCE_URL", + "secrets": [ + { + "name": "SUMO_LOGIC_SOURCE_URL", + "secret": "sumologic_metrics_us1" + } + ], + "max_connections": 10, + "timeout": "30s" + } +} +{{< /code >}} + +## Create or update a Sumo Logic metrics handler + +The `/sumo-logic-metrics-handlers/:sumo-logic-metrics-handler` API endpoint provides HTTP PUT access to create or update a specific `:sumo-logic-metrics-handler` definition, by handler name. + +### Example + +In the following example, an HTTP PUT request is submitted to the `/sumo-logic-metrics-handlers/:sumo-logic-metrics-handler` API endpoint to create `sumologic_http_log_metrics_us2`: + +{{< code shell >}} +curl -X PUT \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "type": "SumoLogicMetricsHandler", + "api_version": "pipeline/v1", + "metadata": { + "name": "sumologic_http_log_metrics_us2" + }, + "spec": { + "url": "$SUMO_LOGIC_SOURCE_URL", + "secrets": [ + { + "name": "SUMO_LOGIC_SOURCE_URL", + "secret": "sumologic_metrics_us2" + } + ], + "max_connections": 10, + "timeout": "30s" + } +}' \ +http://127.0.0.1:8080/api/enterprise/pipeline/v1/namespaces/default/sumo-logic-metrics-handlers/sumologic_http_log_metrics_us2 +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification + +/sumo-logic-metrics-handlers/:sumo-logic-metrics-handler (PUT) | +----------------|------ +description | Creates or updates the specified Sensu Sumo Logic metrics handler. +example URL | http://hostname:8080/api/enterprise/pipeline/v1/namespaces/default/sumo-logic-metrics-handlers/sumologic_http_log_metrics_us2 +payload | {{< code shell >}} +{ + "type": "SumoLogicMetricsHandler", + "api_version": "pipeline/v1", + "metadata": { + "name": "sumologic_http_log_metrics_us2" + }, + "spec": { + "url": "$SUMO_LOGIC_SOURCE_URL", + "secrets": [ + { + "name": "SUMO_LOGIC_SOURCE_URL", + "secret": "sumologic_metrics_us2" + } + ], + "max_connections": 10, + "timeout": "30s" + } +} +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Delete a Sumo Logic metrics handler + +The `/sumo-logic-metrics-handlers/:sumo-logic-metrics-handler` API endpoint provides HTTP DELETE access to delete a Sumo Logic metrics handler from Sensu (specified by the handler name). + +### Example + +The following example shows a request to the `/sumo-logic-metrics-handlers/:sumo-logic-metrics-handler` API endpoint to delete the Sumo Logic metrics handler `sumologic_http_log_metrics_us2`, resulting in a successful `HTTP/1.1 204 No Content` response. + +{{< code shell >}} +curl -X DELETE \ +http://127.0.0.1:8080/api/enterprise/pipeline/v1/namespaces/default/sumo-logic-metrics-handlers/sumologic_http_log_metrics_us2 \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +### API Specification + +/sumo-logic-metrics-handlers/:sumo-logic-metrics-handler (DELETE) | +--------------------------|------ +description | Removes the specified Sumo Logic metrics handler from Sensu. +example url | http://hostname:8080/api/enterprise/pipeline/v1/namespaces/default/sumo-logic-metrics-handlers/sumologic_http_log_metrics_us2 +response codes |
    • **Success**: 204 (No Content)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + +## Get all TCP stream handler resources + +The `/tcp-stream-handlers` API endpoint provides HTTP GET access to [TCP stream handler][1] data. + +### Example {#handlers-get-example} + +The following example demonstrates a GET request to the `/tcp-stream-handlers` API endpoint: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/enterprise/pipeline/v1/namespaces/default/tcp-stream-handlers \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request results in a successful `HTTP/1.1 200 OK` response and a JSON array that contains the [TCP stream handler definitions][1] in the `default` namespace: + +{{< code text >}} +[ + { + "type": "TCPStreamHandler", + "api_version": "pipeline/v1", + "metadata": { + "name": "incident_log", + "namespace": "default", + "created_by": "admin" + }, + "spec": { + "address": "127.0.0.1:4242", + "max_connections": 10, + "max_reconnect_delay": "10s", + "min_reconnect_delay": "10ms", + "tls_ca_cert_file": "", + "tls_cert_file": "", + "tls_key_file": "" + } + }, + { + "type": "TCPStreamHandler", + "api_version": "pipeline/v1", + "metadata": { + "name": "logstash", + "namespace": "default", + "created_by": "admin" + }, + "spec": { + "address": "127.0.0.1:4242", + "max_connections": 10, + "max_reconnect_delay": "10s", + "min_reconnect_delay": "10ms", + "tls_ca_cert_file": "/path/to/tls/ca.pem", + "tls_cert_file": "/path/to/tls/cert.pem", + "tls_key_file": "/path/to/tls/key.pem" + } + } +] +{{< /code >}} + +### API Specification {#handlers-get-specification} + +/tcp-stream-handlers (GET) | +---------------|------ +description | Returns the list of TCP stream handlers. +example url | http://hostname:8080/api/enterprise/pipeline/v1/namespaces/default/tcp-stream-handlers +pagination | This endpoint supports [pagination][2] using the `limit` and `continue` query parameters. +response filtering | This endpoint supports [API response filtering][3]. +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "type": "TCPStreamHandler", + "api_version": "pipeline/v1", + "metadata": { + "name": "incident_log", + "namespace": "default", + "created_by": "admin" + }, + "spec": { + "address": "127.0.0.1:4242", + "max_connections": 10, + "max_reconnect_delay": "10s", + "min_reconnect_delay": "10ms", + "tls_ca_cert_file": "", + "tls_cert_file": "", + "tls_key_file": "" + } + }, + { + "type": "TCPStreamHandler", + "api_version": "pipeline/v1", + "metadata": { + "name": "logstash", + "namespace": "default", + "created_by": "admin" + }, + "spec": { + "address": "127.0.0.1:4242", + "max_connections": 10, + "max_reconnect_delay": "10s", + "min_reconnect_delay": "10ms", + "tls_ca_cert_file": "/path/to/tls/ca.pem", + "tls_cert_file": "/path/to/tls/cert.pem", + "tls_key_file": "/path/to/tls/key.pem" + } + } +] +{{< /code >}} + +## Create a new TCP stream handler + +The `/tcp-stream-handlers` API endpoint provides HTTP POST access to create a TCP stream handler. + +### Example {#handlers-post-example} + +In the following example, an HTTP POST request is submitted to the `/tcp-stream-handlers` API endpoint to create the TCP stream handler `logstash`: + +{{< code shell >}} +curl -X POST \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "api_version": "pipeline/v1", + "type": "TCPStreamHandler", + "metadata": { + "name": "logstash" + }, + "spec": { + "address": "127.0.0.1:4242", + "tls_ca_cert_file": "/path/to/tls/ca.pem", + "tls_cert_file": "/path/to/tls/cert.pem", + "tls_key_file": "/path/to/tls/key.pem", + "max_connections": 10, + "min_reconnect_delay": "10ms", + "max_reconnect_delay": "10s" + } +}' \ +http://127.0.0.1:8080/api/enterprise/pipeline/v1/namespaces/default/tcp-stream-handlers +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#handlers-post-specification} + +/tcp-stream-handlers (POST) | +----------------|------ +description | Creates a Sensu TCP stream handler. +example URL | http://hostname:8080/api/enterprise/pipeline/v1/namespaces/default/tcp-stream-handlers +payload | {{< code shell >}} +{ + "api_version": "pipeline/v1", + "type": "TCPStreamHandler", + "metadata": { + "name": "logstash" + }, + "spec": { + "address": "127.0.0.1:4242", + "tls_ca_cert_file": "/path/to/tls/ca.pem", + "tls_cert_file": "/path/to/tls/cert.pem", + "tls_key_file": "/path/to/tls/key.pem", + "max_connections": 10, + "min_reconnect_delay": "10ms", + "max_reconnect_delay": "10s" + } +} +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Get a specific TCP stream handler + +The `/tcp-stream-handlers/:tcp-stream-handler` API endpoint provides HTTP GET access to [TCP stream handler data][1] for specific `:tcp-stream-handler` definitions, by handler `name`. + +### Example + +The following example queries the `/tcp-stream-handlers/:tcp-stream-handler` API endpoint for the `:tcp-stream-handler` named `logstash`: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/enterprise/pipeline/v1/namespaces/default/tcp-stream-handlers/logstash \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request will return a successful `HTTP/1.1 200 OK` response and a JSON map that contains the requested [`:tcp-stream-handler` definition][1] (in this example, `logstash`): + +{{< code text >}} +{ + "type": "TCPStreamHandler", + "api_version": "pipeline/v1", + "metadata": { + "name": "logstash", + "namespace": "default", + "created_by": "admin" + }, + "spec": { + "address": "127.0.0.1:4242", + "max_connections": 10, + "max_reconnect_delay": "10s", + "min_reconnect_delay": "10ms", + "tls_ca_cert_file": "/path/to/tls/ca.pem", + "tls_cert_file": "/path/to/tls/cert.pem", + "tls_key_file": "/path/to/tls/key.pem" + } +} +{{< /code >}} + +### API Specification + +/tcp-stream-handlers/:tcp-stream-handler (GET) | +---------------------|------ +description | Returns a TCP stream handler. +example url | http://hostname:8080/api/enterprise/pipeline/v1/namespaces/default/tcp-stream-handlers/logstash +response type | Map +response codes |
    • **Success**: 200 (OK)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +{ + "type": "TCPStreamHandler", + "api_version": "pipeline/v1", + "metadata": { + "name": "logstash", + "namespace": "default", + "created_by": "admin" + }, + "spec": { + "address": "127.0.0.1:4242", + "max_connections": 10, + "max_reconnect_delay": "10s", + "min_reconnect_delay": "10ms", + "tls_ca_cert_file": "/path/to/tls/ca.pem", + "tls_cert_file": "/path/to/tls/cert.pem", + "tls_key_file": "/path/to/tls/key.pem" + } +} +{{< /code >}} + +## Create or update a TCP stream handler + +The `/tcp-stream-handlers/:tcp-stream-handler` API endpoint provides HTTP PUT access to create or update a specific `:tcp-stream-handler` definition, by handler name. + +### Example + +In the following example, an HTTP PUT request is submitted to the `/tcp-stream-handlers/:tcp-stream-handler` API endpoint to create the handler `incident_log`: + +{{< code shell >}} +curl -X PUT \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "api_version": "pipeline/v1", + "type": "TCPStreamHandler", + "metadata": { + "name": "incident_log" + }, + "spec": { + "address": "127.0.0.1:4242", + "max_connections": 10, + "min_reconnect_delay": "10ms", + "max_reconnect_delay": "10s" + } +}' \ +http://127.0.0.1:8080/api/enterprise/pipeline/v1/namespaces/default/tcp-stream-handlers/incident_log +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification + +/tcp-stream-handlers/:tcp-stream-handler (PUT) | +----------------|------ +description | Creates or updates the specified Sensu TCP stream handler. +example URL | http://hostname:8080/api/enterprise/pipeline/v1/namespaces/default/tcp-stream-handlers/incident_log +payload | {{< code shell >}} +{ + "api_version": "pipeline/v1", + "type": "TCPStreamHandler", + "metadata": { + "name": "incident_log" + }, + "spec": { + "address": "127.0.0.1:4242", + "max_connections": 10, + "min_reconnect_delay": "10ms", + "max_reconnect_delay": "10s" + } +} +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Delete a TCP stream handler + +The `/tcp-stream-handlers/:tcp-stream-handler` API endpoint provides HTTP DELETE access to delete a TCP stream handler from Sensu (specified by the handler name). + +### Example + +The following example shows a request to the `/tcp-stream-handlers/:tcp-stream-handler` API endpoint to delete the TCP stream handler `incident_log`, resulting in a successful `HTTP/1.1 204 No Content` response: + +{{< code shell >}} +curl -X DELETE \ +http://127.0.0.1:8080/api/enterprise/pipeline/v1/namespaces/default/tcp-stream-handlers/incident_log \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +### API Specification + +/tcp-stream-handlers/:tcp-stream-handler (DELETE) | +--------------------------|------ +description | Removes the specified TCP stream handler from Sensu. +example url | http://hostname:8080/api/enterprise/pipeline/v1/namespaces/default/tcp-stream-handlers/incident_log +response codes |
    • **Success**: 204 (No Content)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + + +[1]: ../../../observability-pipeline/observe-process/tcp-stream-handlers/ +[2]: ../../#pagination +[3]: ../../#response-filtering +[4]: https://tools.ietf.org/html/rfc7396 +[5]: ../../../observability-pipeline/observe-process/sumo-logic-metrics-handlers/ diff --git a/content/sensu-go/6.12/api/enterprise/prune.md b/content/sensu-go/6.12/api/enterprise/prune.md new file mode 100644 index 0000000000..aaf75cb2a1 --- /dev/null +++ b/content/sensu-go/6.12/api/enterprise/prune.md @@ -0,0 +1,109 @@ +--- +title: "enterprise/prune/v1alpha" +description: "Read this API documentation for Sensu enterprise/prune/v1alpha API endpoints, which provide HTTP access to create pruning commands for specific Sensu resources." +enterprise_api_title: "enterprise/prune/v1alpha" +type: "enterprise_api" +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: enterprise +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access pruning via `enterprise/prune/v1alpha` API endpoints in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} + +{{% notice note %}} +**NOTE**: The `enterprise/prune/v1alpha` API endpoints are an alpha feature and may include breaking changes.

    +The pruning operation follows the role-based access control (RBAC) permissions of the current user. +For example, to prune resources in the `dev` namespace, the current user who sends the prune command must have delete access to the `dev` namespace.

    +Requests to `enterprise/prune/v1alpha` API endpoints require you to authenticate with a Sensu [API key](../../#configure-an-environment-variable-for-api-key-authentication) or [access token](../../#authenticate-with-auth-api-endpoints). +The code examples in this document use the [environment variable](../../#configure-an-environment-variable-for-api-key-authentication) `$SENSU_API_KEY` to represent a valid API key in API requests. +{{% /notice %}} + +## Create a new pruning command + +The `/prune/v1alpha` API endpoint provides HTTP POST access to create a pruning command to delete resources that are not specified in the request body. + +### Example {#prune-v1alpha-post-example} + +In the following example, an HTTP POST request is submitted to the `/prune/v1alpha` API endpoint to create a pruning command for the checks specified in the request body in the `dev` namespace created by any user: + +{{< code shell >}} +curl -X POST \ +http://127.0.0.1:8080/api/enterprise/prune/v1alpha\?types\=core/v2.CheckConfig\&allUsers\=true\&namespaces\=dev \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "type": "CheckConfig", + "api_version": "core/v2", + "name": "check-echo", + "namespace": "dev", + "labels": { + "region": "us-west-2", + "sensu.io/managed_by": "sensuctl" + }, + "created_by": "admin" +}' +{{< /code >}} + +The request returns a successful `HTTP/1.1 201 Created` response and a list of the resources that were pruned: + +{{< code text >}} +[ + { + "type": "CheckConfig", + "api_version": "core/v2", + "name": "check-echo", + "namespace": "dev", + "labels": { + "region": "us-west-2", + "sensu.io/managed_by": "sensuctl" + }, + "created_by": "admin" + } +] +{{< /code >}} + +### API Specification {#prune-v1alpha-specification} + +/prune/v1alpha (POST) | +----------------------|------ +description | Creates a pruning command to delete the specified resources. +example URL | http://hostname:8080/api/enterprise/prune/v1alpha?types=core/v2.CheckConfig&allUsers=true&namespaces=dev?types=core/v2.CheckConfig&allUsers=true&namespaces=dev +example payload | {{< code json >}} +{ + "type": "CheckConfig", + "api_version": "core/v2", + "name": "check-echo", + "namespace": "dev", + "labels": { + "region": "us-west-2", + "sensu.io/managed_by": "sensuctl" + }, + "created_by": "admin" +} +{{< /code >}} +query parameters |
    • `type`: The [fully-qualified name][2] of the resource you want to prune. Example: `?type=core/v2.CheckConfig`.
    • `allUsers`: Prune resources created by all users. Mutually exclusive with the `users` parameter. Defaults to false. Example: `?allUsers=true`.
    • `clusterWide`: Prune any cluster-wide (non-namespaced) resources that are not defined in the configuration. Defaults to false. Example: `?clusterWide=true`.
    • `dryRun`: Print the resources that will be pruned but does not actually delete them. Defaults to false. Example: `?dryRun=true`.
    • `labelSelector`: Prune only resources that match the specified labels (accepts multiple values). Labels are a [commercial feature][1]. Example: `?labelSelector=[...]`.
    • `namespaces`: The namespace where you want to apply pruning. Example: `?namespaces=dev`.
    • `users`: Prune only resources that were created by the specified users (accepts multiple values). Defaults to the currently configured sensuctl user. Example: `?users=admin`.
    To use multiple values for the parameters that allow them, you must specify the parameter multiple times (for example, `?users=admin&users=dev`) rather than using a comma-separated list. +output | {{< code text >}} +[ + { + "type": "CheckConfig", + "api_version": "core/v2", + "name": "check-echo", + "namespace": "dev", + "labels": { + "region": "us-west-2", + "sensu.io/managed_by": "sensuctl" + }, + "created_by": "admin" + } +] +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + + +[1]: ../../../commercial/ +[2]: ../../../sensuctl/create-manage-resources/#supported-resource-types diff --git a/content/sensu-go/6.12/api/enterprise/searches.md b/content/sensu-go/6.12/api/enterprise/searches.md new file mode 100644 index 0000000000..f2c5702521 --- /dev/null +++ b/content/sensu-go/6.12/api/enterprise/searches.md @@ -0,0 +1,284 @@ +--- +title: "enterprise/searches/v1" +description: "Read this API documentation for information about Sensu enterprise/searches/v1 API endpoints, including examples for retrieving and managing saved searches." +enterprise_api_title: "enterprise/searches/v1" +type: "enterprise_api" +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: enterprise +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access saved searches in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} + +{{% notice note %}} +**NOTE**: Requests to `enterprise/searches/v1` API endpoints require you to authenticate with a Sensu [API key](../../#configure-an-environment-variable-for-api-key-authentication) or [access token](../../#authenticate-with-auth-api-endpoints). +The code examples in this document use the [environment variable](../../#configure-an-environment-variable-for-api-key-authentication) `$SENSU_API_KEY` to represent a valid API key in API requests. +{{% /notice %}} + +## Get all searches + +The `/searches` API endpoint provides HTTP GET access to the list of saved searches. + +### Example {#searches-get-example} + +The following example demonstrates a GET request to the `/search` API endpoint: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/enterprise/searches/v1/namespaces/default/searches \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request results in a successful `HTTP/1.1 200 OK` response and a JSON array that contains the [search definitions][2] in the `default` namespace: + +{{< code text >}} +[ + { + "type": "Search", + "api_version": "searches/v1", + "metadata": { + "name": "incidents-us-west", + "namespace": "default" + }, + "spec": { + "parameters": [ + "labelSelector:region == \"us-west-1\"", + "status:incident" + ], + "resource": "core.v2/Event" + } + }, + { + "type": "Search", + "api_version": "searches/v1", + "metadata": { + "name": "silenced-events", + "namespace": "default" + }, + "spec": { + "parameters": [ + "silenced:true" + ], + "resource": "core.v2/Event" + } + }, + { + "type": "Search", + "api_version": "searches/v1", + "metadata": { + "name": "web-agent", + "namespace": "default" + }, + "spec": { + "parameters": [ + "class:agent", + "subscription:web" + ], + "resource": "core.v2/Entity" + } + } +] +{{< /code >}} + +### API Specification {#searches-get-specification} + +/searches (GET) | +---------------|------ +description | Returns the list of saved searches. +example url | http://hostname:8080/api/enterprise/searches/v1/namespaces/default/searches +response filtering | This endpoint supports [API response filtering][1]. +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "type": "Search", + "api_version": "searches/v1", + "metadata": { + "name": "incidents-us-west", + "namespace": "default" + }, + "spec": { + "parameters": [ + "labelSelector:region == \"us-west-1\"", + "status:incident" + ], + "resource": "core.v2/Event" + } + }, + { + "type": "Search", + "api_version": "searches/v1", + "metadata": { + "name": "silenced-events", + "namespace": "default" + }, + "spec": { + "parameters": [ + "silenced:true" + ], + "resource": "core.v2/Event" + } + }, + { + "type": "Search", + "api_version": "searches/v1", + "metadata": { + "name": "web-agent", + "namespace": "default" + }, + "spec": { + "parameters": [ + "class:agent", + "subscription:web" + ], + "resource": "core.v2/Entity" + } + } +] +{{< /code >}} + +## Get a specific search {#searchessearch-get} + +The `/searches/:search` API endpoint provides HTTP GET access to a specific `:search` definition, by the saved search `name`. + +### Example {#searchessearch-get-example} + +The following example queries the `/searches/:search` API endpoint for the `:search` named `silenced-events`: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/enterprise/searches/v1/namespaces/default/searches/silenced-events \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request will return a successful `HTTP/1.1 200 OK` response and a JSON map that contains the requested [`:search` definition][2] (in this example, `silenced-events`): + +{{< code text >}} +{ + "type": "Search", + "api_version": "searches/v1", + "metadata": { + "name": "silenced-events", + "namespace": "default" + }, + "spec": { + "parameters": [ + "silenced:true" + ], + "resource": "core.v2/Event" + } +} +{{< /code >}} + +### API Specification {#searchessearch-get-specification} + +/searches/:search (GET) | +---------------------|------ +description | Returns the specified search. +example url | http://hostname:8080/api/enterprise/searches/v1/namespaces/default/searches/silenced-events +response type | Map +response codes |
    • **Success**: 200 (OK)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +{ + "type": "Search", + "api_version": "searches/v1", + "metadata": { + "name": "silenced-events", + "namespace": "default" + }, + "spec": { + "parameters": [ + "silenced:true" + ], + "resource": "core.v2/Event" + } +} +{{< /code >}} + +## Create or update a search {#searchessearch-put} + +The `/searches/:search` API endpoint provides HTTP PUT access to create or update a saved search by the saved search `name`. + +### Example {#searchessearch-put-example} + +In the following example, an HTTP PUT request is submitted to the `/searches/:search` API endpoint to create or update a saved search for events that are silenced. +The request includes the saved search definition in the request body. + +{{< code shell >}} +curl -X PUT \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "type": "Search", + "api_version": "searches/v1", + "metadata": { + "name": "silenced-events", + "namespace": "default" + }, + "spec": { + "parameters": [ + "silenced:true" + ], + "resource": "core.v2/Event" + } +}' \ +http://127.0.0.1:8080/api/enterprise/searches/v1/namespaces/default/searches/silenced-events +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#searchessearch-put-specification} + +/searches/:search (PUT) | +----------------|------ +description | Creates or updates the specified saved search. +example URL | http://hostname:8080/api/enterprise/searches/v1/namespaces/default/searches/silenced-events +payload | {{< code json >}} +{ + "type": "Search", + "api_version": "searches/v1", + "metadata": { + "name": "silenced-events", + "namespace": "default" + }, + "spec": { + "parameters": [ + "silenced:true" + ], + "resource": "core.v2/Event" + } +} +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Delete a search {#searchessearch-delete} + +The `/searches/:search` API endpoint provides HTTP DELETE access to delete a saved search from Sensu (specified by the saved search name). + +### Example {#searchessearch-delete-example} + +The following example shows a request to the `/searches/:search` API endpoint to delete the saved search `silenced-events`, resulting in a successful `HTTP/1.1 204 No Content` response. + +{{< code shell >}} +curl -X DELETE \ +-H "Authorization: Key $SENSU_API_KEY" \ +http://127.0.0.1:8080/api/enterprise/searches/v1/namespaces/default/searches/silenced-events +{{< /code >}} + +### API Specification {#searchessearch-delete-specification} + +/searches/:search (DELETE) | +--------------------------|------ +description | Removes a saved search from Sensu (specified by the search name). +example url | http://hostname:8080/api/enterprise/searches/v1/namespaces/default/searches/silenced-events +response codes |
    • **Success**: 204 (No Content)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + + +[1]: ../../#response-filtering +[2]: ../../../web-ui/searches-reference/ diff --git a/content/sensu-go/6.12/api/enterprise/secrets.md b/content/sensu-go/6.12/api/enterprise/secrets.md new file mode 100644 index 0000000000..211cf42bef --- /dev/null +++ b/content/sensu-go/6.12/api/enterprise/secrets.md @@ -0,0 +1,729 @@ +--- +title: "enterprise/secrets/v1" +description: "Read this API documentation for information about Sensu enterprise/secrets/v1 API endpoints, with examples for managing secrets and secrets providers." +enterprise_api_title: "enterprise/secrets/v1" +type: "enterprise_api" +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: enterprise +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access secrets management in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} + +{{% notice note %}} +**NOTE**: Requests to `enterprise/secrets/v1` API endpoints require you to authenticate with a Sensu [API key](../../#configure-an-environment-variable-for-api-key-authentication) or [access token](../../#authenticate-with-auth-api-endpoints). +The code examples in this document use the [environment variable](../../#configure-an-environment-variable-for-api-key-authentication) `$SENSU_API_KEY` to represent a valid API key in API requests. +{{% /notice %}} + +## Get all secrets providers + +The `/providers` API endpoint provides HTTP GET access to a list of secrets providers. + +### Example {#providers-get-example} + +The following example demonstrates a GET request to the `/providers` API endpoint: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/enterprise/secrets/v1/providers \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request results in a successful `HTTP/1.1 200 OK` response and a JSON array that contains the [secrets provider definitions][1]: + +{{< code text >}} +[ + { + "type": "VaultProvider", + "api_version": "secrets/v1", + "metadata": { + "name": "my_vault", + "created_by": "admin" + }, + "spec": { + "client": { + "address": "https://vaultserver.example.com:8200", + "token": "VAULT_TOKEN", + "version": "v1", + "tls": { + "ca_cert": "/etc/ssl/certs/vault_ca_cert.pem" + }, + "max_retries": 2, + "timeout": "20s", + "rate_limiter": { + "limit": 10.0, + "burst": 100 + } + } + } + } +] +{{< /code >}} + +{{% notice note %}} +**NOTE**: In addition to the `VaultProvider` type, the enterprise/secrets/v1 API also includes the `CyberArkProvider` and `Env` types. +Learn more in the [secrets providers reference](../../../operations/manage-secrets/secrets-providers/). +{{% /notice %}} + +### API Specification {#providers-get-specification} + +/providers (GET) | +---------------|------ +description | Returns the list of secrets providers. +example url | http://hostname:8080/api/enterprise/secrets/v1/providers +query parameters | `types`: Defines which type of secrets provider to retrieve. Join with `&` to retrieve multiple types: `?types=Env&types=CyberArkProvider&types=VaultProvider`. +response filtering | This endpoint supports [API response filtering][3]. +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "type": "VaultProvider", + "api_version": "secrets/v1", + "metadata": { + "name": "my_vault", + "created_by": "admin" + }, + "spec": { + "client": { + "address": "https://vaultserver.example.com:8200", + "token": "VAULT_TOKEN", + "version": "v1", + "tls": { + "ca_cert": "/etc/ssl/certs/vault_ca_cert.pem" + }, + "max_retries": 2, + "timeout": "20s", + "rate_limiter": { + "limit": 10.0, + "burst": 100 + } + } + } + } +] +{{< /code >}} + +## Get a specific secrets provider {#providers-provider-get} + +The `/providers/:provider` API endpoint provides HTTP GET access to data for a specific secrets `:provider`, by provider name. + +### Example {#providers-provider-get-example} + +The following example queries the `/providers/:provider` API endpoint for the requested `:provider`, `my_vault`: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/enterprise/secrets/v1/providers/my_vault \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request will return a successful `HTTP/1.1 200 OK` response and a JSON map that contains the requested [`:provider` definition][1] (in this example, `my_vault`): + +{{< code text >}} +{ + "type": "VaultProvider", + "api_version": "secrets/v1", + "metadata": { + "name": "my_vault", + "created_by": "admin" + }, + "spec": { + "client": { + "address": "https://vaultserver.example.com:8200", + "token": "VAULT_TOKEN", + "version": "v1", + "tls": { + "ca_cert": "/etc/ssl/certs/vault_ca_cert.pem" + }, + "max_retries": 2, + "timeout": "20s", + "rate_limiter": { + "limit": 10.0, + "burst": 100 + } + } + } +} +{{< /code >}} + +### API Specification {#providers-provider-get-specification} + +/providers/:provider (GET) | +---------------------|------ +description | Returns the specified secrets provider. +example url | http://hostname:8080/api/enterprise/secrets/v1/providers/my_vault +response type | Map +response codes |
    • **Success**: 200 (OK)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +{ + "type": "VaultProvider", + "api_version": "secrets/v1", + "metadata": { + "name": "my_vault", + "created_by": "admin" + }, + "spec": { + "client": { + "address": "https://vaultserver.example.com:8200", + "token": "VAULT_TOKEN", + "version": "v1", + "tls": { + "ca_cert": "/etc/ssl/certs/vault_ca_cert.pem" + }, + "max_retries": 2, + "timeout": "20s", + "rate_limiter": { + "limit": 10.0, + "burst": 100 + } + } + } +} +{{< /code >}} + +## Create or update a secrets provider {#providers-provider-put} + +The `/providers/:provider` API endpoint provides HTTP PUT access to create or update a specific `:provider`, by provider name. + +### Example {#providers-provider-put-example} + +The following example demonstrates a request to the `/providers/:provider` API endpoint to update the provider `my_vault`: + +{{< code shell >}} +curl -X PUT \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "type": "VaultProvider", + "api_version": "secrets/v1", + "metadata": { + "name": "my_vault" + }, + "spec": { + "client": { + "address": "https://vaultserver.example.com:8200", + "token": "VAULT_TOKEN", + "version": "v1", + "tls": { + "ca_cert": "/etc/ssl/certs/vault_ca_cert.pem" + }, + "max_retries": 2, + "timeout": "20s", + "rate_limiter": { + "limit": 10.0, + "burst": 100 + } + } + } +}' \ +http://127.0.0.1:8080/api/enterprise/secrets/v1/providers/my_vault +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response and the complete definition for the provider you created or updated. + +### API Specification {#providers-provider-put-specification} + +/providers/:provider (PUT) | +----------------|------ +description | Creates or updates the specified secrets provider. The provider resource and API version cannot be altered. +example URL | http://hostname:8080/api/enterprise/secrets/v1/providers/my_vault +payload | {{< code json >}} +{ + "type": "VaultProvider", + "api_version": "secrets/v1", + "metadata": { + "name": "my_vault" + }, + "spec": { + "client": { + "address": "https://vaultserver.example.com:8200", + "token": "VAULT_TOKEN", + "version": "v1", + "tls": { + "ca_cert": "/etc/ssl/certs/vault_ca_cert.pem" + }, + "max_retries": 2, + "timeout": "20s", + "rate_limiter": { + "limit": 10.0, + "burst": 100 + } + } + } +} +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Delete a secrets provider {#providers-provider-delete} + +The `/providers/:provider` API endpoint provides HTTP DELETE access to delete the specified provider from Sensu. + +### Example {#providers-provider-delete-example} + +The following example shows a request to the `/providers/:provider` API endpoint to delete the provider `my_vault`, resulting in a successful `HTTP/1.1 204 No Content` response: + +{{< code shell >}} +curl -X DELETE \ +-H "Authorization: Key $SENSU_API_KEY" \ +http://127.0.0.1:8080/api/enterprise/secrets/v1/providers/my_vault +{{< /code >}} + +### API Specification {#providers-provider-delete-specification} + +/providers/:provider (DELETE) | +--------------------------|------ +description | Deletes the specified provider from Sensu. +example url | http://hostname:8080/api/enterprise/secrets/v1/providers/my_vault +response codes |
    • **Success**: 204 (No Content)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + +## Get a subset of secrets providers with response filtering + +The `/providers` API endpoint supports [response filtering][3] for a subset of secrets providers data based on labels and the `provider.name` field. + +### Example + +The following example demonstrates a request to the `/providers` API endpoint with [response filtering][3] for only [secrets provider definitions][1] whose name includes `vault`: + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/enterprise/secrets/v1/providers -G \ +--data-urlencode 'fieldSelector=provider.name matches vault' +{{< /code >}} + +The example request will result in a successful `HTTP/1.1 200 OK` response and a JSON array that contains only [provider definitions][1] whose names include `vault`: + +{{< code text >}} +[ + { + "type": "VaultProvider", + "api_version": "secrets/v1", + "metadata": { + "name": "vault_dev", + "created_by": "admin" + }, + "spec": { + "client": { + "address": "http://localhost:8200", + "agent_address": "", + "max_retries": 2, + "rate_limiter": { + "burst": 100, + "limit": 10 + }, + "timeout": "20s", + "tls": null, + "token": "\\u003croot_token\\u003e", + "version": "v2" + } + } + }, + { + "type": "VaultProvider", + "api_version": "secrets/v1", + "metadata": { + "name": "my_vault", + "created_by": "admin" + }, + "spec": { + "client": { + "address": "https://vaultserver.example.com:8200", + "token": "VAULT_TOKEN", + "version": "v1", + "tls": { + "ca_cert": "/etc/ssl/certs/vault_ca_cert.pem" + }, + "max_retries": 2, + "timeout": "20s", + "rate_limiter": { + "limit": 10.0, + "burst": 100 + } + } + } + } +] +{{< /code >}} + +{{% notice note %}} +**NOTE**: Read [API response filtering](../../#response-filtering) for more filter statement examples that demonstrate how to filter responses using different operators with label and field selectors. +{{% /notice %}} + +### API Specification + +/providers (GET) with response filters | +---------------|------ +description | Returns the list of secrets providers that match the [response filters][3] applied in the API request. +example url | http://hostname:8080/api/enterprise/secrets/v1/providers +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "type": "VaultProvider", + "api_version": "secrets/v1", + "metadata": { + "name": "vault_dev", + "created_by": "admin" + }, + "spec": { + "client": { + "address": "http://localhost:8200", + "agent_address": "", + "max_retries": 2, + "rate_limiter": { + "burst": 100, + "limit": 10 + }, + "timeout": "20s", + "tls": null, + "token": "\\u003croot_token\\u003e", + "version": "v2" + } + } + }, + { + "type": "VaultProvider", + "api_version": "secrets/v1", + "metadata": { + "name": "my_vault", + "created_by": "admin" + }, + "spec": { + "client": { + "address": "https://vaultserver.example.com:8200", + "token": "VAULT_TOKEN", + "version": "v1", + "tls": { + "ca_cert": "/etc/ssl/certs/vault_ca_cert.pem" + }, + "max_retries": 2, + "timeout": "20s", + "rate_limiter": { + "limit": 10.0, + "burst": 100 + } + } + } + } +] +{{< /code >}} + +## Get all secrets + +The `/secrets` API endpoint provides HTTP GET access to a list of secrets. + +### Example {#secrets-get-example} + +The following example demonstrates a GET request to the `/secrets` API endpoint: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/enterprise/secrets/v1/namespaces/default/secrets \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request results in a successful `HTTP/1.1 200 OK` response and a JSON array that contains the [secret definitions][2] in the `default` namespace: + +{{< code text >}} +[ + { + "type": "Secret", + "api_version": "secrets/v1", + "metadata": { + "name": "sensu-ansible-token", + "namespace": "default", + "created_by": "admin" + }, + "spec": { + "id": "secret/ansible#token", + "provider": "ansible_vault" + } + } +] +{{< /code >}} + +### API Specification {#secrets-get-specification} + +/secrets (GET) | +---------------|------ +description | Returns the list of secrets for the specified namespace. +example url | http://hostname:8080/api/enterprise/secrets/v1/namespaces/default/secrets +response filtering | This endpoint supports [API response filtering][3]. +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "type": "Secret", + "api_version": "secrets/v1", + "metadata": { + "name": "sensu-ansible-token", + "namespace": "default", + "created_by": "admin" + }, + "spec": { + "id": "secret/ansible#token", + "provider": "ansible_vault" + } + } +] +{{< /code >}} + +## Get a specific secret {#secrets-secret-get} + +The `/secrets/:secret` API endpoint provides HTTP GET access to data for a specific `secret`, by secret name. + +### Example {#secrets-secret-get-example} + +The following example queries the `/secrets/:secret` API endpoint for the requested `:secret`: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/enterprise/secrets/v1/namespaces/default/secrets/sensu-ansible-token \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request will return a successful `HTTP/1.1 200 OK` response and a JSON map that contains the requested [`:secret` definition][2] (in this example, `sensu-ansible-token`): + +{{< code text >}} +{ + "type": "Secret", + "api_version": "secrets/v1", + "metadata": { + "name": "sensu-ansible-token", + "namespace": "default", + "created_by": "admin" + }, + "spec": { + "id": "secret/ansible#token", + "provider": "ansible_vault" + } +} +{{< /code >}} + +### API Specification {#secrets-secret-get-specification} + +/secrets/:secret (GET) | +---------------------|------ +description | Returns the specified secret. +example url | http://hostname:8080/api/enterprise/secrets/v1/namespaces/default/secrets/sensu-ansible-token +response type | Map +response codes |
    • **Success**: 200 (OK)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +{ + "type": "Secret", + "api_version": "secrets/v1", + "metadata": { + "name": "sensu-ansible-token", + "namespace": "default", + "created_by": "admin" + }, + "spec": { + "id": "secret/ansible#token", + "provider": "ansible_vault" + } +} +{{< /code >}} + +## Create or update a secret {#secrets-secret-put} + +The `/secrets/:secret` API endpoint provides HTTP PUT access to create or update a specific `secret`, by secret name. + +### Example {#secrets-secret-put-example} + +The following example demonstrates a request to the `/secrets/:secret` API endpoint to update the secret `sensu-ansible-token`. + +{{< code shell >}} +curl -X PUT \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "type": "Secret", + "api_version": "secrets/v1", + "metadata": { + "name": "sensu-ansible-token", + "namespace": "default" + }, + "spec": { + "id": "secret/ansible#token", + "provider": "ansible_vault" + } +}' \ +http://127.0.0.1:8080/api/enterprise/secrets/v1/namespaces/default/secrets/sensu-ansible-token +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#secrets-secret-put-specification} + +/secrets/:secret (PUT) | +----------------|------ +description | Creates or updates the specified secret. +example URL | http://hostname:8080/api/enterprise/secrets/v1/namespaces/default/secrets/sensu-ansible-token +payload | {{< code json >}} +{ + "type": "Secret", + "api_version": "secrets/v1", + "metadata": { + "name": "sensu-ansible-token", + "namespace": "default" + }, + "spec": { + "id": "secret/ansible#token", + "provider": "ansible_vault" + } +} +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Delete a secret {#secrets-secret-delete} + +The `/secrets/:secret` API endpoint provides HTTP DELETE access to delete the specified secret from Sensu. + +### Example {#secrets-secret-delete-example} + +The following example shows a request to the `/secrets/:secret` API endpoint to delete the secret `sensu-ansible-token`, resulting in a successful `HTTP/1.1 204 No Content` response: + +{{< code shell >}} +curl -X DELETE \ +-H "Authorization: Key $SENSU_API_KEY" \ +http://127.0.0.1:8080/api/enterprise/secrets/v1/namespaces/default/secrets/sensu-ansible-token +{{< /code >}} + +### API Specification {#secrets-secret-delete-specification} + +/secrets/:secret (DELETE) | +--------------------------|------ +description | Deletes the specified secret from Sensu. +example url | http://hostname:8080/api/enterprise/secrets/v1/namespaces/default/secrets/sensu-ansible-token +response codes |
    • **Success**: 204 (No Content)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + +## Get a subset of secrets with response filtering + +The `/secrets` API endpoint supports [response filtering][3] for a subset of secrets data based on labels and the following fields: + +- `secret.name` +- `secret.namespace` +- `secret.provider` +- `secret.id` + +### Example + +The following example demonstrates a request to the `/secrets` API endpoint with [response filtering][3], resulting in a JSON array that contains only [secrets definitions][2] for the `vault` provider. + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/enterprise/secrets/v1/secrets -G \ +--data-urlencode 'fieldSelector=secret.provider == vault' +{{< /code >}} + +The example request will result in a successful `HTTP/1.1 200 OK` response and a JSON array that contains only [secret definitions][1] for the `vault` provider: + +{{< code text >}} +[ + { + "type": "Secret", + "api_version": "secrets/v1", + "metadata": { + "name": "pagerduty_key", + "namespace": "default", + "created_by": "admin" + }, + "spec": { + "id": "secret/pagerduty#key", + "provider": "vault" + } + }, + { + "type": "Secret", + "api_version": "secrets/v1", + "metadata": { + "name": "sensu-ansible", + "namespace": "default", + "created_by": "admin" + }, + "spec": { + "id": "secret/database#password", + "provider": "vault" + } + }, + { + "type": "Secret", + "api_version": "secrets/v1", + "metadata": { + "name": "sumologic_url", + "namespace": "default", + "created_by": "admin" + }, + "spec": { + "id": "secret/sumologic#key", + "provider": "vault" + } + } +] +{{< /code >}} + +{{% notice note %}} +**NOTE**: Read [API response filtering](../../#response-filtering) for more filter statement examples that demonstrate how to filter responses using different operators with label and field selectors. +{{% /notice %}} + +### API Specification + +/secrets (GET) with response filters | +---------------|------ +description | Returns the list of secrets that match the [response filters][3] applied in the API request. +example url | http://hostname:8080/api/enterprise/secrets/v1/secrets +response type | Array +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "type": "Secret", + "api_version": "secrets/v1", + "metadata": { + "name": "pagerduty_key", + "namespace": "default", + "created_by": "admin" + }, + "spec": { + "id": "secret/pagerduty#key", + "provider": "vault" + } + }, + { + "type": "Secret", + "api_version": "secrets/v1", + "metadata": { + "name": "sensu-ansible", + "namespace": "default", + "created_by": "admin" + }, + "spec": { + "id": "secret/database#password", + "provider": "vault" + } + }, + { + "type": "Secret", + "api_version": "secrets/v1", + "metadata": { + "name": "sumologic_url", + "namespace": "default", + "created_by": "admin" + }, + "spec": { + "id": "secret/sumologic#key", + "provider": "vault" + } + } +] +{{< /code >}} + + +[1]: ../../../operations/manage-secrets/secrets-providers/ +[2]: ../../../operations/manage-secrets/secrets/ +[3]: ../../#response-filtering diff --git a/content/sensu-go/6.12/api/enterprise/webconfig.md b/content/sensu-go/6.12/api/enterprise/webconfig.md new file mode 100644 index 0000000000..0ee16332ae --- /dev/null +++ b/content/sensu-go/6.12/api/enterprise/webconfig.md @@ -0,0 +1,394 @@ +--- +title: "enterprise/web/v1" +description: "Read this API documentation for information about Sensu enterprise/web/v1 API endpoints, which provide HTTP access to the global Sensu web UI configuration." +enterprise_api_title: "enterprise/web/v1" +type: "enterprise_api" +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: enterprise +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access web UI configuration in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} + +{{% notice note %}} +**NOTE**: Requests to `enterprise/web/v1` API endpoints require you to authenticate with a Sensu [API key](../../#configure-an-environment-variable-for-api-key-authentication) or [access token](../../#authenticate-with-auth-api-endpoints). +The code examples in this document use the [environment variable](../../#configure-an-environment-variable-for-api-key-authentication) `$SENSU_API_KEY` to represent a valid API key in API requests. +{{% /notice %}} + +## Get the web UI configuration + +The `/config` API endpoint provides HTTP GET access to the global web UI configuration. + +### Example {#config-get-example} + +The following example demonstrates a GET request to the `/config` API endpoint: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/enterprise/web/v1/config \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' +{{< /code >}} + +The request results in a successful `HTTP/1.1 200 OK` response and a JSON array that contains the [web UI configuration definitions][1]: + +{{< code text >}} +[ + { + "type": "GlobalConfig", + "api_version": "web/v1", + "metadata": { + "name": "custom-web-ui", + "created_by": "admin" + }, + "spec": { + "always_show_local_cluster": false, + "default_preferences": { + "poll_interval": 120000, + "page_size": 500, + "serialization_format": "YAML", + "theme": "sensu" + }, + "license_expiry_reminder": "1080h0m0s", + "link_policy": { + "allow_list": true, + "urls": [ + "https://example.com", + "steamapp://34234234", + "//google.com", + "//*.google.com", + "//bob.local", + "https://grafana-host/render/metrics?width=500&height=250#sensu.io.graphic" + ] + }, + "page_preferences": [ + { + "order": "LASTSEEN", + "page": "entities", + "page_size": 50, + "selector": "proxy in entity.subscriptions" + }, + { + "order": "NAME", + "page": "checks", + "page_size": 100 + } + ], + "signin_message": "with your **LDAP or system credentials**" + } + } +] +{{< /code >}} + +### API Specification {#config-get-specification} + +/web (GET) | +---------------|------ +description | Returns the list of global web UI configurations. +example url | http://hostname:8080/api/enterprise/web/v1/config +response type | Map +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +[ + { + "type": "GlobalConfig", + "api_version": "web/v1", + "metadata": { + "name": "custom-web-ui", + "created_by": "admin" + }, + "spec": { + "always_show_local_cluster": false, + "default_preferences": { + "poll_interval": 120000, + "page_size": 500, + "serialization_format": "YAML", + "theme": "sensu" + }, + "license_expiry_reminder": "1080h0m0s", + "link_policy": { + "allow_list": true, + "urls": [ + "https://example.com", + "steamapp://34234234", + "//google.com", + "//*.google.com", + "//bob.local", + "https://grafana-host/render/metrics?width=500&height=250#sensu.io.graphic" + ] + }, + "page_preferences": [ + { + "order": "LASTSEEN", + "page": "entities", + "page_size": 50, + "selector": "proxy in entity.subscriptions" + }, + { + "order": "NAME", + "page": "checks", + "page_size": 100 + } + ], + "signin_message": "with your **LDAP or system credentials**" + } + } +] +{{< /code >}} + +## Get a specific web UI configuration {#configglobalconfig-get} + +The `/config/:globalconfig` API endpoint provides HTTP GET access to global web UI configuration data, specified by configuration name. + +### Example {#configglobalconfig-get-example} + +The following example queries the `/config/:globalconfig` API endpoint for the `:globalconfig` named `custom-web-ui`: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/enterprise/web/v1/config/custom-web-ui \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The request will return a successful `HTTP/1.1 200 OK` response and a JSON map that contains the requested [`:globalconfig` definition][1] (in this example, `custom-web-ui`): + +{{< code text >}} +{ + "type": "GlobalConfig", + "api_version": "web/v1", + "metadata": { + "name": "custom-web-ui", + "created_by": "admin" + }, + "spec": { + "always_show_local_cluster": false, + "default_preferences": { + "poll_interval": 120000, + "page_size": 500, + "serialization_format": "YAML", + "theme": "sensu" + }, + "license_expiry_reminder": "1080h0m0s", + "link_policy": { + "allow_list": true, + "urls": [ + "https://example.com", + "steamapp://34234234", + "//google.com", + "//*.google.com", + "//bob.local", + "https://grafana-host/render/metrics?width=500&height=250#sensu.io.graphic" + ] + }, + "page_preferences": [ + { + "order": "LASTSEEN", + "page": "entities", + "page_size": 50, + "selector": "proxy in entity.subscriptions" + }, + { + "order": "NAME", + "page": "checks", + "page_size": 100 + } + ], + "signin_message": "with your **LDAP or system credentials**" + } +} +{{< /code >}} + +### API Specification {#configglobalconfig-get-specification} + +/config/:globalconfig (GET) | +---------------------|------ +description | Returns the specified global web UI configuration. +example url | http://hostname:8080/api/enterprise/web/v1/config/custom-web-ui +response type | Map +response codes |
    • **Success**: 200 (OK)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +{ + "type": "GlobalConfig", + "api_version": "web/v1", + "metadata": { + "name": "custom-web-ui", + "created_by": "admin" + }, + "spec": { + "always_show_local_cluster": false, + "default_preferences": { + "poll_interval": 120000, + "page_size": 500, + "serialization_format": "YAML", + "theme": "sensu" + }, + "license_expiry_reminder": "1080h0m0s", + "link_policy": { + "allow_list": true, + "urls": [ + "https://example.com", + "steamapp://34234234", + "//google.com", + "//*.google.com", + "//bob.local", + "https://grafana-host/render/metrics?width=500&height=250#sensu.io.graphic" + ] + }, + "page_preferences": [ + { + "order": "LASTSEEN", + "page": "entities", + "page_size": 50, + "selector": "proxy in entity.subscriptions" + }, + { + "order": "NAME", + "page": "checks", + "page_size": 100 + } + ], + "signin_message": "with your **LDAP or system credentials**" + } +} +{{< /code >}} + +## Create and update a web UI configuration {#configglobalconfig-put} + +The `/config/:globalconfig` API endpoint provides HTTP PUT access to create and update global web UI configurations, specified by configuration name. + +### Example {#configglobalconfighooks-put-example} + +In the following example, an HTTP PUT request is submitted to the `/config/:globalconfig` API endpoint to update the `custom-web-ui` configuration: + +{{< code shell >}} +curl -X PUT \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "type": "GlobalConfig", + "api_version": "web/v1", + "metadata": { + "name": "custom-web-ui" + }, + "spec": { + "always_show_local_cluster": false, + "default_preferences": { + "poll_interval": 120000, + "page_size": 500, + "serialization_format": "YAML", + "theme": "sensu" + }, + "license_expiry_reminder": "1080h0m0s", + "link_policy": { + "allow_list": true, + "urls": [ + "https://example.com", + "steamapp://34234234", + "//google.com", + "//*.google.com", + "//bob.local", + "https://grafana-host/render/metrics?width=500&height=250#sensu.io.graphic" + ] + }, + "page_preferences": [ + { + "order": "LASTSEEN", + "page": "entities", + "page_size": 50, + "selector": "proxy in entity.subscriptions" + }, + { + "order": "NAME", + "page": "checks", + "page_size": 100 + } + ], + "signin_message": "with your **LDAP or system credentials**" + } +}' \ +http://127.0.0.1:8080/api/enterprise/web/v1/config/custom-web-ui +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#configglobalconfig-put-specification} + +/config/:globalconfig (PUT) | +----------------|------ +description | Creates or updates the specified global web UI configuration. +example URL | http://hostname:8080/api/enterprise/web/v1/config/custom-web-ui +payload | {{< code json >}} +{ + "type": "GlobalConfig", + "api_version": "web/v1", + "metadata": { + "name": "custom-web-ui" + }, + "spec": { + "always_show_local_cluster": false, + "default_preferences": { + "poll_interval": 120000, + "page_size": 500, + "serialization_format": "YAML", + "theme": "sensu" + }, + "license_expiry_reminder": "1080h0m0s", + "link_policy": { + "allow_list": true, + "urls": [ + "https://example.com", + "steamapp://34234234", + "//google.com", + "//*.google.com", + "//bob.local", + "https://grafana-host/render/metrics?width=500&height=250#sensu.io.graphic" + ] + }, + "page_preferences": [ + { + "order": "LASTSEEN", + "page": "entities", + "page_size": 50, + "selector": "proxy in entity.subscriptions" + }, + { + "order": "NAME", + "page": "checks", + "page_size": 100 + } + ], + "signin_message": "with your **LDAP or system credentials**" + } +} +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Delete a web UI configuration {#configglobalconfig-delete} + +The `/config/:globalconfig` API endpoint provides HTTP DELETE access to delete a global web UI configuration from Sensu, specified by the configuration name. + +### Example {#configglobalconfig-delete-example} + +The following example shows a request to the `/config/:globalconfig` API endpoint to delete the global web UI configuration named `custom-web-ui`, resulting in a successful `HTTP/1.1 204 No Content` response: + +{{< code shell >}} +curl -X DELETE \ +-H "Authorization: Key $SENSU_API_KEY" \ +http://127.0.0.1:8080/api/enterprise/web/v1/config/custom-web-ui +{{< /code >}} + +### API Specification {#configglobalconfig-delete-specification} + +/config/:globalconfig (DELETE) | +--------------------------|------ +description | Removes the specified global web UI configuration from Sensu. +example url | http://hostname:8080/api/enterprise/web/v1/config/custom-web-ui +response codes |
    • **Success**: 204 (No Content)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + + +[1]: ../../../web-ui/webconfig-reference/ diff --git a/content/sensu-go/6.12/api/other/_index.md b/content/sensu-go/6.12/api/other/_index.md new file mode 100644 index 0000000000..ad7e62ad9d --- /dev/null +++ b/content/sensu-go/6.12/api/other/_index.md @@ -0,0 +1,21 @@ +--- +title: "Other APIs" +description: "Sensu offers API endpoints for basic authentication, checking cluster health checks, and retrieving metrics, license information, and version information." +product: "Sensu Go" +version: "6.12" +weight: 20 +layout: "single" +toc: false +menu: + sensu-go-6.12: + parent: api + identifier: other +--- + +In addition to the [core/v2 API][1] and [enterprise APIs][2], Sensu offers endpoints for basic authentication, health, license, metrics, and version: + +{{< otherapiListing >}} + + +[1]: ../core/ +[2]: ../enterprise/ diff --git a/content/sensu-go/6.12/api/other/auth.md b/content/sensu-go/6.12/api/other/auth.md new file mode 100644 index 0000000000..86a2fb4593 --- /dev/null +++ b/content/sensu-go/6.12/api/other/auth.md @@ -0,0 +1,134 @@ +--- +title: "/auth" +description: "Read this API documentation for information about Sensu /auth API endpoints, with examples for retrieving authentication credentials and testing their validity." +other_api_title: "/auth" +type: "other_api" +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: other +--- + +## Generate an access token and a refresh token {#auth-get} + +The `/auth` API endpoint provides HTTP GET access to generate an access token and a refresh token using Sensu's basic authentication. + +The access and refresh tokens are [JSON Web Tokens (JWTs)][2] that Sensu issues to record the details of users' authenticated Sensu sessions. +The backend digitally signs these tokens, and the tokens can't be changed without invalidating the signature. + +### Example {#auth-get-example} + +The following example queries the `/auth` API endpoint with a given username and password to determine whether the credentials are valid and retrieve an access token and a refresh token: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/auth \ +-u myusername:mypassword +{{< /code >}} + +The request results in a successful `HTTP/1.1 200 OK` response to indicate that the credentials are valid, along with an access token and a refresh token: + +{{< code text >}} +{ + "access_token": "eyJhbGciOiJIUzI1NiIs...", + "expires_at": 1544582187, + "refresh_token": "eyJhbGciOiJIUzI1NiIs..." +} +{{< /code >}} + +### API Specification {#auth-get-specification} + +/auth (GET) | | +---------------------|------ +description | Generates an access and a refresh token used for accessing the API using Sensu's basic authentication. Access tokens last for approximately 15 minutes. When your token expires, you should receive a `401 Unauthorized` response from the API. To generate a new access token, use the [`/auth/token` API endpoint](#authtoken-post). +example url | http://hostname:8080/auth +output | {{< code text >}} +{ + "access_token": "eyJhbGciOiJIUzI1NiIs...", + "expires_at": 1544582187, + "refresh_token": "eyJhbGciOiJIUzI1NiIs..." +} +{{< /code >}} +response codes |
    • **Valid credentials**: 200 (OK)
    • **Invalid credentials**: 401 (Unauthorized)
    • **Error**: 500 (Internal Server Error)
    + +## Test basic auth user credentials {#authtest-get} + +The `/auth/test` API endpoint provides HTTP GET access to test basic authentication user credentials that were created with Sensu's built-in [basic authentication][1]. + +{{% notice note %}} +**NOTE**: The `/auth/test` endpoint only tests user credentials created with Sensu's built-in [basic authentication](../../../operations/control-access#use-built-in-basic-authentication). +It does not test user credentials defined via an authentication provider like [Lightweight Directory Access Protocol (LDAP)](../../../operations/control-access/ldap-auth), [Active Directory (AD)](../../../operations/control-access/ad-auth/), or [OpenID Connect 1.0 protocol (OIDC)](../../../operations/control-access/oidc-auth/). +{{% /notice %}} + +### Example {#authtest-get-example} + +In the following example, querying the `/auth/test` API endpoint with a given username and password should return an `HTTP/1.1 200 OK` response, indicating that the credentials are valid: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/auth/test \ +-u myusername:mypassword +{{< /code >}} + +### API Specification {#authtest-get-specification} + +/auth/test (GET) | | +---------------------|------ +description | Tests basic authentication credentials (username and password) that were created with Sensu's [core/v2/users API][1]. +example url | http://hostname:8080/auth/test +response codes |
    • **Valid credentials**: 200 (OK)
    • **Invalid credentials**: 401 (Unauthorized)
    • **Error**: 500 (Internal Server Error)
    + +## Renew an access token {#authtoken-post} + +The `/auth/token` API endpoint provides HTTP POST access to renew an access token. + +### Example {#authtoken-post-example} + +In the following example, an HTTP POST request is submitted to the `/auth/token` API endpoint to generate a valid access token. +The request includes the refresh token in the request body. + +{{< code shell >}} +curl -X POST \ +http://127.0.0.1:8080/auth/token \ +-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \ +-H 'Content-Type: application/json' \ +-d '{"refresh_token": "eyJhbGciOiJIUzI1NiIs..."}' +{{< /code >}} + +The request results in a successful `HTTP/1.1 200 OK` response, along with the new access token: + +{{< code text >}} +{ + "access_token": "eyJhbGciOiJIUzI1NiIs...", + "expires_at": 1544582187, + "refresh_token": "eyJhbGciOiJIUzI1NiIs..." +} +{{< /code >}} + +The access and refresh tokens are [JSON Web Tokens (JWTs)][2] that Sensu issues to record the details of users' authenticated Sensu sessions. +The backend digitally signs these tokens, and the tokens can't be changed without invalidating the signature. + +### API Specification {#authtoken-post-specification} + +/auth/token (POST) | | +---------------------|------ +description | Generates a new access token using a refresh token and an expired access token. +example url | http://hostname:8080/auth/token +example payload | {{< code shell >}} +{ + "refresh_token": "eyJhbGciOiJIUzI1NiIs..." +} +{{< /code >}} +output | {{< code text >}} +{ + "access_token": "eyJhbGciOiJIUzI1NiIs...", + "expires_at": 1544582187, + "refresh_token": "eyJhbGciOiJIUzI1NiIs..." +} +{{< /code >}} +response codes |
    • **Success**: 200 (OK)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + + +[1]: ../../../operations/control-access#use-built-in-basic-authentication +[2]: https://tools.ietf.org/html/rfc7519 diff --git a/content/sensu-go/6.12/api/other/health.md b/content/sensu-go/6.12/api/other/health.md new file mode 100644 index 0000000000..1b223dc545 --- /dev/null +++ b/content/sensu-go/6.12/api/other/health.md @@ -0,0 +1,187 @@ +--- +title: "/health" +description: "Read this API documentation for information about Sensu /health API endpoints, including examples for retrieving health details about your Sensu instance." +other_api_title: "/health" +type: "other_api" +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: other +--- + +## Get health data for your Sensu instance + +The `/health` API endpoint provides HTTP GET access to health data for your Sensu instance. + +### Example {#health-get-example} + +The following example demonstrates a GET request to the `/health` API endpoint: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/health +{{< /code >}} + +The request results in a successful `HTTP/1.1 200 OK` response and a JSON map that contains Sensu [health][1] data: + +{{< code text >}} +{ + "Alarms": null, + "ClusterHealth": [ + { + "MemberID": 2882886652148554927, + "MemberIDHex": "8923110df66458af", + "Name": "default", + "Err": "", + "Healthy": true + } + ], + "Header": { + "cluster_id": 4255616344056076734, + "member_id": 2882886652148554927, + "raft_term": 26 + }, + "PostgresHealth": [ + { + "Name": "my-postgres", + "Active": false, + "Healthy": false + } + ] +} +{{< /code >}} + +{{% notice note %}} +**NOTE**: If your Sensu instance is not configured to use a [PostgreSQL datastore](../../../operations/deploy-sensu/datastore/#scale-event-storage), the health payload will not include `PostgresHealth`. +{{% /notice %}} + +### API Specification {#health-get-specification} + +/health (GET) | +-----------------|------ +description | Returns health information about the Sensu instance. +example url | http://hostname:8080/health +query parameters | `timeout`: Defines the timeout when querying etcd. Default is `3`. +response type | Map +response codes |
    • **Success**: 200 (OK)
    • **Error**: 400 (Bad Request)
    {{% notice note %}} +**NOTE**: The HTTP response codes for the health endpoint indicate whether your request reached Sensu rather than the health of your Sensu instance. +To determine the health of your Sensu instance, you must process the JSON response body for your request. +The [health specification](../../../operations/monitor-sensu/health/#health-specification) describes each attribute in the response body. +{{% /notice %}} +output | {{< code text >}} +{ + "Alarms": null, + "ClusterHealth": [ + { + "MemberID": 2882886652148554927, + "MemberIDHex": "8923110df66458af", + "Name": "default", + "Err": "", + "Healthy": true + } + ], + "Header": { + "cluster_id": 4255616344056076734, + "member_id": 2882886652148554927, + "raft_term": 26 + }, + "PostgresHealth": [ + { + "Name": "my-postgres", + "Active": false, + "Healthy": false + } + ] +} +{{< /code >}} + +## Get health data for your agent transport + +The `/health` API endpoint provides HTTP GET access to health data for your Sensu agent transport via the backend WebSocket. +Sensu backend `/health` API information is duplicated by this agent transport API endpoint as an affordance to satisfy the load balancing and security requirements of some deployments. + +### Example + +The following example demonstrates a GET request to the backend WebSocket `/health` API endpoint using the default WebSocket port 8081: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8081/health +{{< /code >}} + +The request results in a successful `HTTP/1.1 200 OK` response and a JSON map that contains Sensu agent transport status: + +{{< code text >}} +{ + "Alarms": null, + "ClusterHealth": [ + { + "MemberID": 2882886652148554927, + "MemberIDHex": "8923110df66458af", + "Name": "default", + "Err": "", + "Healthy": true + } + ], + "Header": { + "cluster_id": 4255616344056076734, + "member_id": 2882886652148554927, + "raft_term": 26 + }, + "PostgresHealth": [ + { + "Name": "my-postgres", + "Active": false, + "Healthy": false + } + ] +} +{{< /code >}} + +{{% notice note %}} +**NOTE**: If your Sensu instance is not configured to use a [PostgreSQL datastore](../../../operations/deploy-sensu/datastore/#scale-event-storage), the health payload will not include `PostgresHealth`. +{{% /notice %}} + +### API Specification + +/health (GET) | +-----------------|------ +description | Returns health information about the Sensu agent transport. +example url | http://hostname:8081/health +query parameters | `timeout`: Defines the timeout when querying etcd. Default is `3`. +response type | Map +response codes |
    • **Success**: 200 (OK)
    • **Error**: 400 (Bad Request)
    {{% notice note %}} +**NOTE**: The HTTP response codes for the health endpoint indicate whether your request reached Sensu rather than the health of your Sensu instance. +To determine the health of your Sensu instance, you must process the JSON response body for your request. +The [health specification](../../../operations/monitor-sensu/health/#health-specification) describes each attribute in the response body. +{{% /notice %}} +output | {{< code text >}} +{ + "Alarms": null, + "ClusterHealth": [ + { + "MemberID": 2882886652148554927, + "MemberIDHex": "8923110df66458af", + "Name": "default", + "Err": "", + "Healthy": true + } + ], + "Header": { + "cluster_id": 4255616344056076734, + "member_id": 2882886652148554927, + "raft_term": 26 + }, + "PostgresHealth": [ + { + "Name": "my-postgres", + "Active": false, + "Healthy": false + } + ] +} +{{< /code >}} + + +[1]: ../../../operations/monitor-sensu/health/ diff --git a/content/sensu-go/6.12/api/other/license.md b/content/sensu-go/6.12/api/other/license.md new file mode 100644 index 0000000000..70f2ca0035 --- /dev/null +++ b/content/sensu-go/6.12/api/other/license.md @@ -0,0 +1,232 @@ +--- +title: "/license" +description: "Read this API documentation for information about Sensu /license API endpoints, with examples for retrieving, activating, and deleting your commercial license." +other_api_title: "/license" +type: "other_api" +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: other +--- + +{{% notice note %}} +**NOTE**: Requests to `/license` API endpoints require you to authenticate with a Sensu [API key](../../#configure-an-environment-variable-for-api-key-authentication) or [access token](../../#authenticate-with-auth-api-endpoints). +The code examples in this document use the [environment variable](../../#configure-an-environment-variable-for-api-key-authentication) `$SENSU_API_KEY` to represent a valid API key in API requests. +{{% /notice %}} + +For more information about commercial features designed for enterprises, read [Get started with commercial features][1]. + +## Get the active license configuration + +The `/license` API endpoint provides HTTP GET access to the active license configuration. + +### Example {#license-get-example} + +The following example demonstrates a GET request to the `/license` API endpoint: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/enterprise/licensing/v2/license \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' +{{< /code >}} + +The request results in a successful `HTTP/1.1 200 OK` response and a JSON map that contains the [license definition][4]: + +{{< code text >}} +{ + "type": "LicenseFile", + "api_version": "licensing/v2", + "metadata": { + "labels": { + "sensu.io/entity-count": "10", + "sensu.io/entity-limit": "100" + } + }, + "spec": { + "license": { + "version": 1, + "issuer": "Sensu, Inc.", + "accountName": "my_account", + "accountID": 1234567, + "issued": "2019-01-01T13:40:25-08:00", + "validUntil": "2020-01-01T13:40:25-08:00", + "plan": "managed", + "features": [ + "all" + ], + "signature": { + "algorithm": "PSS", + "hashAlgorithm": "SHA256", + "saltLength": 20 + } + }, + "signature": "XXXXXXXXXX", + "metadata": {} + } +} +{{< /code >}} + +### API Specification {#license-get-specification} + +/license (GET) | +---------------|------ +description | Returns the active commercial license configuration. To download your license, [log in to your Sensu account][2] or [contact the Sensu sales team for a free trial][3]. +example url | http://hostname:8080/api/enterprise/licensing/v2/license +response type | Map +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +{ + "type": "LicenseFile", + "api_version": "licensing/v2", + "metadata": { + "labels": { + "sensu.io/entity-count": "10", + "sensu.io/entity-limit": "100" + } + }, + "spec": { + "license": { + "version": 1, + "issuer": "Sensu, Inc.", + "accountName": "my_account", + "accountID": 1234567, + "issued": "2019-01-01T13:40:25-08:00", + "validUntil": "2020-01-01T13:40:25-08:00", + "plan": "managed", + "features": [ + "all" + ], + "signature": { + "algorithm": "PSS", + "hashAlgorithm": "SHA256", + "saltLength": 20 + } + }, + "signature": "XXXXXXXXXX", + "metadata": {} + } +} +{{< /code >}} + +## Activate a commercial license + +The `/license` API endpoint provides HTTP PUT access to activate a commercial license. + +{{% notice note %}} +**NOTE**: For [clustered configurations](../../../operations/deploy-sensu/cluster-sensu), you only need to activate your license for one of the backends within the cluster. +{{% /notice %}} + +### Example {#license-put-example} + +In the following example, an HTTP PUT request is submitted to the `/license` API endpoint to create the license definition: + +{{< code shell >}} +curl -X PUT \ +-H "Authorization: Key $SENSU_API_KEY" \ +-H 'Content-Type: application/json' \ +-d '{ + "type": "LicenseFile", + "api_version": "licensing/v2", + "metadata": { + "labels": { + "sensu.io/entity-count": "10", + "sensu.io/entity-limit": "100" + } + }, + "spec": { + "license": { + "version": 1, + "issuer": "Sensu, Inc.", + "accountName": "my_account", + "accountID": 1234567, + "issued": "2019-01-01T13:40:25-08:00", + "validUntil": "2020-01-01T13:40:25-08:00", + "plan": "managed", + "features": [ + "all" + ], + "signature": { + "algorithm": "PSS", + "hashAlgorithm": "SHA256", + "saltLength": 20 + } + }, + "signature": "XXXXXXXXXX", + "metadata": {} + } +}' \ +http://127.0.0.1:8080/api/enterprise/licensing/v2/license +{{< /code >}} + +The request will return a successful `HTTP/1.1 201 Created` response. + +### API Specification {#license-put-specification} + +/license (PUT) | +---------------|------ +description | Activates a commercial license or updates an existing license configuration. To download your license, [log in to your Sensu account][2] or [contact the Sensu sales team for a free trial][3]. +example url | http://hostname:8080/api/enterprise/licensing/v2/license +payload | {{< code json >}} +{ + "type": "LicenseFile", + "api_version": "licensing/v2", + "metadata": { + "labels": { + "sensu.io/entity-count": "10", + "sensu.io/entity-limit": "100" + } + }, + "spec": { + "license": { + "version": 1, + "issuer": "Sensu, Inc.", + "accountName": "my_account", + "accountID": 1234567, + "issued": "2019-01-01T13:40:25-08:00", + "validUntil": "2020-01-01T13:40:25-08:00", + "plan": "managed", + "features": [ + "all" + ], + "signature": { + "algorithm": "PSS", + "hashAlgorithm": "SHA256", + "saltLength": 20 + } + }, + "signature": "XXXXXXXXXX", + "metadata": {} + } +} +{{< /code >}} +response codes |
    • **Success**: 201 (Created)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +## Delete a commercial license + +The `/license` API endpoint provides HTTP DELETE access to remove a commercial license. + +### Example {#license-delete-example} + +The following example shows a request to the `/license` API endpoint to delete the commercial license, resulting in a successful `HTTP/1.1 204 No Content` response. + +{{< code shell >}} +curl -X DELETE \ +http://127.0.0.1:8080/api/enterprise/licensing/v2/license \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +### API Specification {#license-delete-specification} + +/license (DELETE) | +-------------------|------ +description | Removes the commercial license. +example url | http://hostname:8080/api/enterprise/licensing/v2/license +response codes |
    • **Success**: 204 (No Content)
    • **Missing**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + + +[1]: ../../../commercial/ +[2]: https://account.sensu.io/ +[3]: https://sensu.io/contact?subject=contact-sales +[4]: ../../../operations/maintain-sensu/license/ diff --git a/content/sensu-go/6.12/api/other/metrics.md b/content/sensu-go/6.12/api/other/metrics.md new file mode 100644 index 0000000000..ee4cbd070d --- /dev/null +++ b/content/sensu-go/6.12/api/other/metrics.md @@ -0,0 +1,71 @@ +--- +title: "/metrics" +description: "Read this API documentation to use the Sensu /metrics API endpoint, which provides HTTP access to internal Sensu metrics in Prometheus format." +other_api_title: "/metrics" +type: "other_api" +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: other +--- + +## Get Sensu metrics + +The `/metrics` API endpoint provides HTTP GET access to internal Sensu metrics in [Prometheus][1] format, including embedded etcd, memory usage, garbage collection, and gRPC metrics. + +### Example {#metrics-get-example} + +The following example demonstrates a GET request to the `/metrics` API endpoint: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/metrics +{{< /code >}} + +The request results in a successful `HTTP/1.1 200 OK` response and plaintext output that contains internal Sensu metrics: + +{{< code text >}} +# HELP etcd_debugging_mvcc_compact_revision The revision of the last compaction in store. +# TYPE etcd_debugging_mvcc_compact_revision gauge +etcd_debugging_mvcc_compact_revision 300 +# HELP etcd_debugging_mvcc_current_revision The current revision of store. +# TYPE etcd_debugging_mvcc_current_revision gauge +etcd_debugging_mvcc_current_revision 316 +# HELP etcd_debugging_mvcc_db_compaction_keys_total Total number of db keys compacted. +# TYPE etcd_debugging_mvcc_db_compaction_keys_total counter +etcd_debugging_mvcc_db_compaction_keys_total 274 +# HELP etcd_debugging_mvcc_db_compaction_pause_duration_milliseconds Bucketed histogram of db compaction pause duration. +# TYPE etcd_debugging_mvcc_db_compaction_pause_duration_milliseconds histogram +etcd_debugging_mvcc_db_compaction_pause_duration_milliseconds_bucket{le="1"} 0 +etcd_debugging_mvcc_db_compaction_pause_duration_milliseconds_bucket{le="2"} 0 +... +{{< /code >}} + +### API Specification {#metrics-get-specification} + +/metrics (GET) | +---------------|------ +description | Returns internal Sensu metrics in Prometheus format, including embedded etcd, memory usage, garbage collection, and gRPC metrics. +example url | http://hostname:8080/metrics +response type | [Prometheus-formatted][1] plaintext +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +# HELP etcd_debugging_mvcc_compact_revision The revision of the last compaction in store. +# TYPE etcd_debugging_mvcc_compact_revision gauge +etcd_debugging_mvcc_compact_revision 300 +# HELP etcd_debugging_mvcc_current_revision The current revision of store. +# TYPE etcd_debugging_mvcc_current_revision gauge +etcd_debugging_mvcc_current_revision 316 +# HELP etcd_debugging_mvcc_db_compaction_keys_total Total number of db keys compacted. +# TYPE etcd_debugging_mvcc_db_compaction_keys_total counter +etcd_debugging_mvcc_db_compaction_keys_total 274 +# HELP etcd_debugging_mvcc_db_compaction_pause_duration_milliseconds Bucketed histogram of db compaction pause duration. +# TYPE etcd_debugging_mvcc_db_compaction_pause_duration_milliseconds histogram +etcd_debugging_mvcc_db_compaction_pause_duration_milliseconds_bucket{le="1"} 0 +etcd_debugging_mvcc_db_compaction_pause_duration_milliseconds_bucket{le="2"} 0 +... +{{< /code >}} + + +[1]: https://prometheus.io/docs/concepts/data_model/ diff --git a/content/sensu-go/6.12/api/other/ready.md b/content/sensu-go/6.12/api/other/ready.md new file mode 100644 index 0000000000..f2e84d2246 --- /dev/null +++ b/content/sensu-go/6.12/api/other/ready.md @@ -0,0 +1,105 @@ +--- +title: "/ready" +description: "Read this API documentation for information about using Sensu's /ready API endpoints to learn whether the Sensu instance is ready to serve API requests." +other_api_title: "/ready" +type: "other_api" +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: other +--- + +## Get API readiness data for your Sensu instance + +The `/ready` API endpoint provides HTTP GET access to information about whether your Sensu instance is ready to serve API requests. + +### Example + +The following example demonstrates a GET request to the `/ready` API endpoint: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/ready +{{< /code >}} + +The request results in a successful `HTTP/1.1 200 OK` response and a text response body: + +{{< code text >}} +ready +{{< /code >}} + +If the backend configuration includes an [`api-serve-wait-time`][2] duration, the request will result in an `HTTP/1.1 503 Service Unavailable` response. +Until the `api-serve-wait-time` duration expires, the text response body will state that the API is unavailable: + +{{< code text >}} +API unavailable during startup. +See api-serve-wait-time settings. +{{< /code >}} + +{{% notice note %}} +**NOTE**: `503 Service Unavailable` responses include a `Retry-After` header that lists the specified `api-serve-wait-time` duration. +{{% /notice %}} + +### API Specification + +/ready (GET) | +-----------------|------ +description | Returns information about whether the Sensu instance is ready to serve API requests. +example url | http://hostname:8080/ready +response type | text +response codes |
    • **Success**: 200 (OK)
    • **Error**: 503 (Service Unavailable)
    +output | 200 (OK):

    {{< code text >}} +ready +{{< /code >}}
    503 (Service Unavailable):

    {{< code text >}} +API unavailable during startup. +See api-serve-wait-time settings. +{{< /code >}} + +## Get agent connection readiness data for your Sensu instance + +The `/ready` agent transport API endpoint provides HTTP GET access to information about whether your Sensu agent transport is ready to accept agent WebSocket connections. + +### Example + +The following example demonstrates a GET request to the backend agent transport `/ready` endpoint using the default agent listener port 8081: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8081/ready +{{< /code >}} + +The request results in a successful `HTTP/1.1 200 OK` response and a text response body: + +{{< code text >}} +ready +{{< /code >}} + +If the backend configuration includes an [`agent-serve-wait-time`][2] duration, the request will result in an `HTTP/1.1 503 Service Unavailable` response. +Until the `agent-serve-wait-time` duration expires, the text response body will state that agentd is unavailable: + +{{< code text >}} +agentd temporarily unavailable during startup +{{< /code >}} + +{{% notice note %}} +**NOTE**: `503 Service Unavailable` responses include a `Retry-After` header that lists the specified `agent-serve-wait-time` duration. +{{% /notice %}} + +### API Specification + +/ready (GET) | +-----------------|------ +description | Returns information about whether the Sensu instance is ready to accept agent connections. +example url | http://hostname:8081/ready +response type | text +response codes |
    • **Success**: 200 (OK)
    • **Error**: 503 (Service Unavailable)
    +output | 200 (OK):

    {{< code text >}} +ready +{{< /code >}}
    503 (Service Unavailable):

    {{< code text >}} +agentd temporarily unavailable during startup +{{< /code >}} + + +[1]: ../../../observability-pipeline/observe-schedule/backend/#api-serve-wait-time +[2]: ../../../observability-pipeline/observe-schedule/backend/#agent-serve-wait-time diff --git a/content/sensu-go/6.12/api/other/version.md b/content/sensu-go/6.12/api/other/version.md new file mode 100644 index 0000000000..a9525ef502 --- /dev/null +++ b/content/sensu-go/6.12/api/other/version.md @@ -0,0 +1,54 @@ +--- +title: "/version" +description: "Read this API documentation for information about the Sensu /version API endpoint, which provides HTTP access to Sensu and etcd versions." +other_api_title: "/version" +type: "other_api" +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: other +--- + +## Get the Sensu backend and etcd versions + +The `/version` API endpoint provides HTTP GET access to the Sensu backend and etcd versions for the Sensu instance. + +### Example {#version-get-example} + +The following example demonstrates a GET request to the `/version` API endpoint: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/version +{{< /code >}} + +The request results in a successful `HTTP/1.1 200 OK` response and a JSON map that contains Sensu version data: + +{{< code text >}} +{ + "etcd": { + "etcdserver": "3.5.0", + "etcdcluster": "3.5.0" + }, + "sensu_backend": "6.4.0" +} +{{< /code >}} + +### API Specification {#version-get-specification} + +/version (GET) | | +--------------------|------ +description | Returns the etcd server version and Sensu backend version. For clustered Sensu installations with the default embedded etcd, also returns the etcd cluster version (which may not match the etcd server version or the cluster versions of other backends in the cluster). +example url | http://hostname:8080/version +response type | Map +response codes |
    • **Success**: 200 (OK)
    • **Error**: 500 (Internal Server Error)
    +output | {{< code text >}} +{ + "etcd": { + "etcdserver": "3.5.0", + "etcdcluster": "3.5.0" + }, + "sensu_backend": "6.4.0" +} +{{< /code >}} diff --git a/content/sensu-go/6.12/catalog/_index.md b/content/sensu-go/6.12/catalog/_index.md new file mode 100644 index 0000000000..4afc2296c6 --- /dev/null +++ b/content/sensu-go/6.12/catalog/_index.md @@ -0,0 +1,49 @@ +--- +title: "Sensu Catalog" +description: "Read the Sensu Catalog documentation to deploy effective monitoring and observability solutions, add catalog integrations, and create your own private catalog." +product: "Sensu Go" +version: "6.12" +weight: 55 +layout: "single" +toc: true +menu: + sensu-go-6.12: + identifier: catalog +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access the Sensu Catalog in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../commercial/). +{{% /notice %}} + +{{% notice note %}} +**NOTE**: The Sensu Catalog is in public preview and is subject to change. +{{% /notice %}} + +The Sensu Catalog is a collection of Sensu integrations that provide reference implementations for monitoring and observability and help you integrate Sensu with the platforms and tools you're already using. +Catalog integrations are self-service and designed to help you scale up with fewer barriers. + +## Use the official Sensu Catalog in the web UI + +In the official Sensu Catalog in the web UI, users install integrations by following prompts and providing custom information. +Sensu then applies any customizations to the integration's resource definitions and deploys the integration configuration to agents in real time. + +No external configuration management is required, and users can deploy effective monitoring and observability resources even if they aren't familiar with the Sensu APIs, sensuctl, or the monitoring-as-code workflow. + +Read [Configure integrations in the Sensu Catalog][1] to learn about the official Sensu Catalog in the web UI. + +## Create your own catalog of integrations + +Instead of using the official Sensu Catalog, you can create a private catalog of custom integrations and make it available to you users within the Sensu web UI. + +Read the [Catalog integrations reference][3] to learn how to structure your catalog repository, create integration definitions, and use the catalog-api command line interface tool to convert integration files into static API content. + +Follow [Build a private catalog of Sensu integrations][2] to create your own catalog. + +Read the [Catalog API][4] documentation to learn more about the requests the catalog-api tool makes to generate the files to display in the Sensu Catalog. + + +[1]: sensu-catalog/ +[2]: build-private-catalog/ +[3]: catalog-reference/ +[4]: catalog-api/ diff --git a/content/sensu-go/6.12/catalog/build-private-catalog.md b/content/sensu-go/6.12/catalog/build-private-catalog.md new file mode 100644 index 0000000000..8cba896cff --- /dev/null +++ b/content/sensu-go/6.12/catalog/build-private-catalog.md @@ -0,0 +1,216 @@ +--- +title: "Build a private catalog of Sensu integrations" +linkTitle: "Build a Private Catalog" +guide_title: "Build a private catalog of Sensu integrations" +type: "guide" +description: "Use Sensu's catalog-api tool to build your own private catalog of customized integrations and serve it to users directly in the Sensu web UI." +weight: 40 +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: catalog +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access the Sensu Catalog and integrations in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../commercial/). +{{% /notice %}} + +{{% notice note %}} +**NOTE**: The Sensu Catalog is in public preview and is subject to change. +{{% /notice %}} + +The [Sensu Catalog][1] is a collection of Sensu integrations that provide reference implementations for effective monitoring and observability. +The official Sensu Catalog is available in the [web UI][2], but you can also create a private catalog of custom integrations and make it available to users in place of the official Sensu Catalog. + +## Requirements + +To follow this guide, install the Sensu [backend][5], make sure at least one Sensu [agent][6] is running, and install and configure [sensuctl][7]. + +You will also need a GitHub repository that stores the integration files you want to include in your private catalog. +Before you begin, make sure that the repository follows the required [organizational framework][3]. + +To serve your private catalog, you will need an endpoint URL that is fetchable for your web UI users. + +## Update URLs in integration asset builds (optional) + +{{% notice note %}} +**NOTE**: If your catalog assets are stored publicly, you do not need to complete this step. +Continue to [Install the catalog-api command line tool](#install-the-catalog-api-command-line-interface-tool). +{{% /notice %}} + +If the assets for your private catalog are stored behind a firewall or are otherwise not publicly available, update the asset definitions in your `sensu-resources.yaml` files to use the endpoint URL that will serve your catalog. + +For example, in the official Sensu Catalog repository, asset definitions include `assets.bonsai.sensu.io` in the `builds.url` values: + +{{< code yaml >}} +--- +type: Asset +api_version: core/v2 +metadata: + name: sensu/nginx-check + namespace: default +spec: + builds: + - filters: + - entity.system.os == 'linux' + - entity.system.arch == 'arm' + - entity.system.arm_version == 6 + headers: null + sha512: 6471e770fa4232068e1d96b2ad79529483b23dcae109932f095a3d1e59fa22410205c2eb63948e2651120b217b5bd908856d3cc318af803a45cc531c837a992e + url: https://assets.bonsai.sensu.io/02bff14ff7f692daab5cace39dcc6e184751285a/nginx-check_0.1.0_linux_armv6.tar.gz + - filters: + - entity.system.os == 'linux' + - entity.system.arch == 'arm' + - entity.system.arm_version == 7 + headers: null + sha512: 714e777c214fd5a7210b67030eb761f5d8c7f8e9ba55f6a0d64872f43f27848eaf51c17bd7b3e3efbdc419d4e4754c6143c705b06ddd750009f8068872e5d35d + url: https://assets.bonsai.sensu.io/02bff14ff7f692daab5cace39dcc6e184751285a/nginx-check_0.1.0_linux_armv7.tar.gz + - filters: ... +{{< /code >}} + +If assets are not publicly available, replace `assets.bonsai.sensu.io` with your preferred URL in asset `builds.url` values in all `sensu-resources.yaml` files before you continue. +You do not need to change the asset `builds.SHA512` values. + +## Install the catalog-api command line interface tool + +The catalog-api command line interface tool is an open-source static API generator: it renders static HTTP API content that the Sensu web UI can consume. + +To install the catalog-api tool: + +1. Clone the Sensu Catalog API repository and navigate to the local catalog-api repository: +{{< code shell >}} +git clone https://github.com/sensu/catalog-api && cd catalog-api +{{< /code >}} + +2. Build the catalog-api tool: +{{< code shell >}} +go build +{{< /code >}} + +3. Exit your local copy of the catalog-api repository: +{{< code shell >}} +cd .. +{{< /code >}} + +## Clone and validate the integration repository + +The catalog-api tool consumes content from a repository that includes all the files required to build a catalog of integrations. +Follow these steps to clone your repository and validate that all files are organized properly: + +1. Clone the repository that stores your Sensu integrations. +Replace with the URL for your integrations repository uses Sensu's public integration repository: +{{< code shell >}} +git clone +{{< /code >}} + +2. Navigate to your local copy of the repository that stores the Sensu integrations. +Replace with the repository name (for example, for https://github.com/sensu/catalog, the is `catalog`): +{{< code shell >}} +cd +{{< /code >}} + +3. Validate the integration repository contents: +{{< code shell >}} +../catalog-api/catalog-api catalog validate +{{< /code >}} + + The response lists the integrations found in the local integration repository: + + {{< code text >}} +11:05AM INF Found integration version name=ansible-tower-remediation namespace=ansible source=path version=99991231.0.0 +11:05AM INF Found integration version name=aws-alb-monitoring namespace=aws source=path version=99991231.0.0 +11:05AM INF Found integration version name=aws-ec2-monitoring namespace=aws source=path version=99991231.0.0 +... +11:05AM INF Found integration version name=wavefront-metrics namespace=wavefront source=path version=99991231.0.0 +{{< /code >}} + +## Generate the private catalog + +With a validated repository, you can generate your private catalog locally. +The `generate` subcommand generates the static API in a temporary directory, `/tmp/generated-api/`: + +{{< code shell >}} +../catalog-api/catalog-api catalog generate +{{< /code >}} + +To specify a different temporary directory, use the `--temp-dir` command line flag: + +{{< code shell >}} +../catalog-api/catalog-api catalog generate --temp-dir /tmp/2523661925/release +{{< /code >}} + +## Publish the static API to an endpoint + +Once you generate your private catalog in a temporary directory, you can serve the output on any HTTP service and publish it to any endpoint. +For example, you can copy the private catalog contents from the temporary directory to a storage service and use a content delivery network (CDN) to serve the content from your storage service to the endpoint URL. + +The only requirement is that the endpoint URL must be fetchable for your web UI users. +The web UI fetches catalog content from your endpoint; the Sensu backend does not serve any of the catalog content. + +## Create a UI GlobalConfig definition + +Use Sensu's GlobalConfig resource to display the private catalog in the Sensu web UI. +Create a GlobalConfig definition that includes the endpoint URL for your private catalog as the `url` value (this example uses `https://catalog.sensu.io:443`): + +{{< language-toggle >}} + +{{< code shell "YML" >}} +cat << EOF | sensuctl create +--- +type: GlobalConfig +api_version: web/v1 +metadata: + name: private-catalog +spec: + always_show_local_cluster: true + catalog: + url: "https://catalog.sensu.io:443" + release_version: version +EOF +{{< /code >}} + +{{< code shell "JSON" >}} +cat << EOF | sensuctl create +{ + "type": "GlobalConfig", + "api_version": "web/v1", + "metadata": { + "name": "private-catalog" + }, + "spec": { + "always_show_local_cluster": true, + "catalog": { + "url": "https://catalog.sensu.io:443", + "release_version": "version" + } + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + +## Confirm the private catalog is available in the web UI + +Log into the Sensu web UI at the URL specified in your GlobalConfig resource and navigate to the Catalog page. +The Catalog page should include all of the integrations in your repository. + +## What's next + +Review the official [Sensu Catalog repository][4] as an example of repository setup and integration configuration. + +The Catalog integrations reference includes the [integration specification][10] as well as details about the [catalog-api command line interface tool][8] and the [server subcommand][9], which you can use to serve integrations from your local environment during development. + + +[1]: ../sensu-catalog/ +[2]: ../../web-ui/ +[3]: ../catalog-reference/#catalog-repository-example +[4]: https://github.com/sensu/catalog +[5]: ../../operations/deploy-sensu/install-sensu/#install-the-sensu-backend +[6]: ../../operations/deploy-sensu/install-sensu/#install-sensu-agents +[7]: ../../operations/deploy-sensu/install-sensu/#install-sensuctl +[8]: ../catalog-reference/#catalog-api-command-line-interface-tool +[9]: ../catalog-reference/#server-subcommand +[10]: ../catalog-reference/#integration-specification diff --git a/content/sensu-go/6.12/catalog/catalog-api.md b/content/sensu-go/6.12/catalog/catalog-api.md new file mode 100644 index 0000000000..7a0f0a79b6 --- /dev/null +++ b/content/sensu-go/6.12/catalog/catalog-api.md @@ -0,0 +1,475 @@ +--- +title: "Catalog API" +description: "Use the Sensu Catalog API to generate static API content that the web UI can consume. Build your own private catalog of Sensu integrations." +product: "Sensu Go" +version: "6.12" +weight: 80 +layout: "single" +toc: true +menu: + sensu-go-6.12: + parent: catalog +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access the Catalog API in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../commercial/). +{{% /notice %}} + +{{% notice note %}} +**NOTE**: The Sensu Catalog is in public preview and is subject to change. +{{% /notice %}} + +The Catalog API is a static API that the [catalog-api command line tool][1] generates from a repository of integrations, such as https://github.com/sensu/catalog. +The Sensu web UI uses the generated API files to determine which integrations to display in the Sensu Catalog. + +## Get the latest catalog SHA-256 checksum + +Retrieves the latest catalog content version's SHA-256 checksum. +The Sensu web UI uses the checksum information to determine the latest API subpath. + +### Example + +The following example queries the Sensu Catalog API for the latest content version: + +{{< code shell >}} +curl -X GET \ +/version.json +{{< /code >}} + +The request returns the latest catalog content version's SHA-256 checksum and the time of the last update (in seconds since the Unix epoch): + +{{< code text >}} +{ + "release_sha256": "af3c54b86b90fac8977f1bdc80d955002dd3f441bdbb4cc603c94abbb929dcf6", + "last_updated": 1643664852 +} +{{< /code >}} + +### API Specification + +/version.json (GET) | | +---------------------|------ +description | Retrieves the latest content version's SHA-256 checksum, which the Sensu web UI uses to determine the latest API subpath. Also returns the time of the last update in seconds since the Unix epoch. +endpoint | /version.json +output | {{< code text >}} +{ + "release_sha256": "af3c54b86b90fac8977f1bdc80d955002dd3f441bdbb4cc603c94abbb929dcf6", + "last_updated": 1643664852 +} +{{< /code >}} +response codes | The Catalog API is statically generated, so response codes indicate an issue with the webserver that is serving the content.
    • **Error**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + +## Get all integration namespaces and names + +Retrieves the list of integration namespaces and names for the catalog. + +### Example + +The following example queries the Sensu Catalog API for integration namespaces and names: + +{{< code shell >}} +curl -X GET \ +/af3c54b86b90fac8977f1bdc80d955002dd3f441bdbb4cc603c94abbb929dcf6/v1/catalog.json +{{< /code >}} + +The request returns the list of integration namespaces and names: + +{{< code text >}} +{ + "namespaced_integrations": { + "nginx": [ + "nginx-monitoring" + ], + "system": [ + "host-monitoring" + ] + } +} +{{< /code >}} + +### API Specification + +//v1/catalog.json (GET) | | +---------------------|------ +description | Retrieves the list of integration namespaces and names for the catalog. +endpoint | //v1/catalog.json +output | {{< code text >}} +{ + "namespaced_integrations": { + "nginx": [ + "nginx-monitoring" + ], + "system": [ + "host-monitoring" + ] + } +} +{{< /code >}} +response codes | The Catalog API is statically generated, so response codes indicate an issue with the webserver that is serving the content.
    • **Error**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + +## Get the configuration and versions for an integration + +For the specified integration, retrieves the configuration for the latest version and a list of +versions. + +### Example + +The following example queries the Sensu Catalog API for an integration's configuration and versions: + +{{< code shell >}} +curl -X GET \ +/af3c54b86b90fac8977f1bdc80d955002dd3f441bdbb4cc603c94abbb929dcf6/v1/nginx/nginx-monitoring.json +{{< /code >}} + +The request returns the latest content version's SHA-256 checksum and the time of the last content update in seconds since the Unix epoch: + +{{< code text >}} +{ + "metadata": { + "name": "nginx-monitoring", + "namespace": "nginx" + }, + "display_name": "NGINX Monitoring", + "class": "community", + "contributors": [ + "@nixwiz", + "@calebhailey" + ], + "provider": "agent/check", + "short_description": "NGINX monitoring", + "supported_platforms": [ + "darwin", + "linux", + "windows" + ], + "tags": [ + "http", + "nginx", + "webserver" + ], + "versions": [ + "20220125.0.0", + "20220126.0.0" + ] +}{{< /code >}} + +### API Specification + +//v1/\/\.json (GET) | | +---------------------|------ +description | Retrieves the specified integration's latest configuration and a list of versions. +endpoint | //v1/\/\.json +output | {{< code text >}} +{ + "metadata": { + "name": "nginx-monitoring", + "namespace": "nginx" + }, + "display_name": "NGINX Monitoring", + "class": "community", + "contributors": [ + "@nixwiz", + "@calebhailey" + ], + "provider": "agent/check", + "short_description": "NGINX monitoring", + "supported_platforms": [ + "darwin", + "linux", + "windows" + ], + "tags": [ + "http", + "nginx", + "webserver" + ], + "versions": [ + "20220125.0.0", + "20220126.0.0" + ] +}{{< /code >}} +response codes | The Catalog API is statically generated, so response codes indicate an issue with the webserver that is serving the content.
    • **Error**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + +## Get all versions for an integration + +Retrieves the list of available versions for the specified integration. + +### Example + +The following example queries the Sensu Catalog API for an integration's available versions: + +{{< code shell >}} +curl -X GET \ +/af3c54b86b90fac8977f1bdc80d955002dd3f441bdbb4cc603c94abbb929dcf6/v1/nginx/nginx-monitoring/versions.json +{{< /code >}} + +The request returns the integration's available versions: + +{{< code text >}} +[ + "20220125.0.0", + "20220126.0.0" +] +{{< /code >}} + +### API Specification + +//v1/\/\/versions.json (GET) | | +---------------------|------ +description | Retrieves a list of the available versions for the specified integration. +endpoint | //v1/\/\/versions.json +output | {{< code text >}} +[ + "20220125.0.0", + "20220126.0.0" +] +{{< /code >}} +response codes | The Catalog API is statically generated, so response codes indicate an issue with the webserver that is serving the content.
    • **Error**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + +## Get the configuration for an integration version + +Retrieves the configuration for the specified version of an integration. + +### Example + +The following example queries the Sensu Catalog API for the specified version of an integration: + +{{< code shell >}} +curl -X GET \ +/af3c54b86b90fac8977f1bdc80d955002dd3f441bdbb4cc603c94abbb929dcf6/v1/nginx/nginx-monitoring/20220125.0.0.json +{{< /code >}} + +The request returns the configuration for the specified version of the integration: + +{{< code text >}} +{ + "metadata": { + "name": "nginx-monitoring", + "namespace": "nginx" + }, + "class": "community", + "contributors": [ + "@nixwiz", + "@calebhailey" + ], + "provider": "agent/check", + "short_description": "NGINX monitoring", + "supported_platforms": [ + "darwin", + "linux", + "windows" + ], + "tags": [ + "http", + "nginx", + "webserver" + ], + "version": "20220125.0.0" +} +{{< /code >}} + +### API Specification + +//v1/\/\/\.json (GET) | | +---------------------|------ +description | Retrieves the latest content version's SHA-256 checksum, which the Sensu web UI uses to determine the latest API subpath. +endpoint | //v1/\/\/\.json +output | {{< code text >}} +{ + "metadata": { + "name": "nginx-monitoring", + "namespace": "nginx" + }, + "class": "community", + "contributors": [ + "@nixwiz", + "@calebhailey" + ], + "provider": "agent/check", + "short_description": "NGINX monitoring", + "supported_platforms": [ + "darwin", + "linux", + "windows" + ], + "tags": [ + "http", + "nginx", + "webserver" + ], + "version": "20220125.0.0" +} +{{< /code >}} +response codes | The Catalog API is statically generated, so response codes indicate an issue with the webserver that is serving the content.
    • **Error**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + +## Get the Sensu resources for an integration + +Retrieves the the Sensu resources for the specified integration version, in JSON format. + +{{% notice note %}} +**NOTE**: The `//v1////sensu-resources.json` endpoint does not include assets in the retreived Sensu resources. +{{% /notice %}} + +### Example + +The following example queries the Sensu Catalog API for the Sensu resources for the specified integration version: + +{{< code shell >}} +curl -X GET \ +/af3c54b86b90fac8977f1bdc80d955002dd3f441bdbb4cc603c94abbb929dcf6/v1/nginx/nginx-monitoring/20220125.0.0/sensu-resources.json +{{< /code >}} + +The request returns the Sensu resources for the requested integration version: + +{{< code text >}} +{ + "api_version": "core/v2", + "metadata": { + "name": "nginx-healthcheck" + }, + "spec": { + "command": "check-nginx-status.rb --url {{ .annotations.check_nginx_status_url | default \"http://localhost:80/nginx_status\" }}", + "interval": 30, + "pipelines": [ + { + "api_version": "core/v2", + "name": "alerts", + "type": "Pipeline" + }, + { + "api_version": "core/v2", + "name": "incident-management", + "type": "Pipeline" + } + ], + "publish": true, + "runtime_assets": [ + "sensu-plugins/sensu-plugins-nginx:3.1.2", + "sensu/sensu-ruby-runtime:0.0.10" + ], + "subscriptions": [ + "nginx" + ], + "timeout": 10 + }, + "type": "CheckConfig" +} +{{< /code >}} + +### API Specification + +//v1/\/\/\/sensu-resources.json (GET) | | +---------------------|------ +description | Retrieves the the Sensu resources (except assets) for the requested integration version, in JSON format. +endpoint | //v1/\/\/\/sensu-resources.json +output | {{< code text >}} +{ + "api_version": "core/v2", + "metadata": { + "name": "nginx-healthcheck" + }, + "spec": { + "command": "check-nginx-status.rb --url {{ .annotations.check_nginx_status_url | default \"http://localhost:80/nginx_status\" }}", + "interval": 30, + "pipelines": [ + { + "api_version": "core/v2", + "name": "alerts", + "type": "Pipeline" + }, + { + "api_version": "core/v2", + "name": "incident-management", + "type": "Pipeline" + } + ], + "publish": true, + "runtime_assets": [ + "sensu-plugins/sensu-plugins-nginx:3.1.2", + "sensu/sensu-ruby-runtime:0.0.10" + ], + "subscriptions": [ + "nginx" + ], + "timeout": 10 + }, + "type": "CheckConfig" +} +{{< /code >}} +response codes | The Catalog API is statically generated, so response codes indicate an issue with the webserver that is serving the content.
    • **Error**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + +## Get the integration README + +Retrieves the README for the specified integration version in Markdown format. + +### Example + +The following example queries the Sensu Catalog API for the README for the specified integration version: + +{{< code shell >}} +curl -X GET \ +/af3c54b86b90fac8977f1bdc80d955002dd3f441bdbb4cc603c94abbb929dcf6/v1/nginx/nginx-monitoring/20220125.0.0/readme.md +{{< /code >}} + +The request returns the README for the specified integration version in Markdown format. + +### API Specification + +//v1/\/\/\/readme.md (GET) | | +---------------------|------ +description | Retrieves the README for the specified integration version in Markdown format. +endpoint | //v1/\/\/\/readme.md +output | README in Markdown format +response codes | The Catalog API is statically generated, so response codes indicate an issue with the webserver that is serving the content.
    • **Error**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + +## Get the integration changelog + +Retrieves the changelog for the specified integration version in Markdown format. + +### Example + +The following example queries the Sensu Catalog API for the changelog for the specified integration version: + +{{< code shell >}} +curl -X GET \ +/af3c54b86b90fac8977f1bdc80d955002dd3f441bdbb4cc603c94abbb929dcf6/v1/nginx/nginx-monitoring/20220125.0.0/changelog.md +{{< /code >}} + +The request returns the changelog for the specified integration version in Markdown format. + +### API Specification + +//v1/\/\/\/changelog.png (GET) | | +---------------------|------ +description | Retrieves the changelog for the specified integration version in Markdown format. +endpoint | //v1/\/\/\/changelog.md +output | Changelog in Markdown format +response codes | The Catalog API is statically generated, so response codes indicate an issue with the webserver that is serving the content.
    • **Error**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + +## Get the integration logo + +Retrieves the logo for the specified integration version in PNG format. + +### Example + +The following example queries the Sensu Catalog API for the logo for the specified integration version: + +{{< code shell >}} +curl -X GET \ +/af3c54b86b90fac8977f1bdc80d955002dd3f441bdbb4cc603c94abbb929dcf6/v1/nginx/nginx-monitoring/20220125.0.0/logo.md +{{< /code >}} + +The request returns the logo for the specified integration version in PNG format. + +### API Specification + +//v1/\/\/\/logo.png (GET) | | +---------------------|------ +description | Retrieves the logo for the specified integration version in PNG format. +endpoint | //v1/\/\/\/logo.md +output | Logo in PNG format +response codes | The Catalog API is statically generated, so response codes indicate an issue with the webserver that is serving the content.
    • **Error**: 404 (Not Found)
    • **Error**: 500 (Internal Server Error)
    + + +[1]: ../catalog-reference/#catalog-api-command-line-interface-tool diff --git a/content/sensu-go/6.12/catalog/catalog-reference.md b/content/sensu-go/6.12/catalog/catalog-reference.md new file mode 100644 index 0000000000..410df36ee8 --- /dev/null +++ b/content/sensu-go/6.12/catalog/catalog-reference.md @@ -0,0 +1,1446 @@ +--- +title: "Catalog integrations reference" +linkTitle: "Catalog Integrations Reference" +reference_title: "Catalog integrations" +type: "reference" +description: "Create integrations that allow teams to configure observability for the systems you rely on and serve them in your own Sensu Catalog." +weight: 60 +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: catalog +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access the Sensu Catalog and integrations in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../commercial/). +{{% /notice %}} + +{{% notice note %}} +**NOTE**: The Sensu Catalog is in public preview and is subject to change. +{{% /notice %}} + +The [Sensu Catalog][1] is a collection of Sensu integrations that provide reference implementations for effective observability. +The contents of the official Sensu Catalog are periodically published with the Sensu Catalog API, which is hosted at https://catalog.sensu.io and displayed within the Sensu web UI. + +When users install integrations in the Sensu web UI, they receive prompts to enter information. +For example, the DNS Monitoring integration includes prompts for the domain name, record type, record class, servers, and port to query. +Sensu then applies the user's customizations to the integration's resource definitions and automatically deploys the integration configuration to agents in real time. +No external configuration management is required. + +Integration definitions resemble other Sensu resources, but Sensu Go does not process them directly. +Instead, the [catalog-api][32] command line interface tool uses integration definitions along with the other files in the catalog repository, like READMEs and dashboard images, to generate a [static Catalog API][2]. +The Sensu web UI uses the generated API files to determine which integrations to display in the Sensu Catalog. + +The Sensu Catalog provides a way for you and your teams to configure powerful real-time monitoring and observability for the systems you rely on. +Integrations are self-service, and the Catalog is designed to help you scale up with fewer barriers. + +## Integration example + +This example shows an integration definition for NGINX monitoring. +Integration definitions are saved as the `sensu-integration.yaml` file in a [catalog repository][15]: + +{{< code yml >}} +--- +api_version: catalog/v1 +type: Integration +metadata: + namespace: nginx + name: nginx-monitoring +spec: + class: supported + provider: monitoring + display_name: NGINX Monitoring + short_description: Monitor NGINX service health and collect metrics + supported_platforms: + - darwin + - linux + - windows + tags: + - http + - nginx + - webserver + - service + contributors: + - "@nixwiz" + - "@calebhailey" + prompts: + - type: section + title: Configure NGINX URL and Monitoring Thresholds + - type: markdown + body: | + Specify the NGINX stub status URL and alerting thresholds for numbers of active and waiting connections. + - type: question + name: default_url + required: false + input: + type: string + title: NGINX stub status URL + description: Enter the NGINX stub_status URL + default: http://127.0.0.1:80/nginx_status + - type: question + name: nginx_active_warn + required: false + input: + type: integer + title: Maximum active connections + description: >- + Enter the maximum number of active connections to allow before sending a WARNING event (default is `300`) + default: 300 + - type: question + name: nginx_waiting_warn + required: false + input: + type: integer + title: Maximum waiting connections + description: >- + Enter the maximum number of waiting connections to allow before sending a WARNING event (default is `30`) + default: 30 + - type: section + title: Configure Sensu Subscriptions + - type: markdown + body: | + Specify the subscriptions for Sensu agents that should execute the `nginx-metrics` check. + - type: question + name: subscriptions + input: + type: array + items: + type: string + title: Sensu Subscriptions + ref: core/v2/entity/subscriptions + default: + - nginx + - type: section + title: Pipeline Configuration + - type: markdown + body: | + Name the [pipelines] you want to use to process NGINX Monitoring integration data. + [pipelines]: https://docs.sensu.io/sensu-go/latest/observability-pipeline/observe-process/pipelines/ + - type: question + name: alerts_pipeline + required: false + input: + type: string + title: Alert pipeline name + description: >- + Which pipeline do you want to use for alerts due to failures this integration detects? + ref: core/v2/pipeline/metadata/name + refFilter: .labels.provider == "alerts" + - type: question + name: incidents_pipeline + required: false + input: + type: string + title: Incident pipeline name + description: >- + Which pipeline do you want to use to process incidents due to failures this integration detects? + ref: core/v2/pipeline/metadata/name + refFilter: .labels.provider == "incidents" + - type: question + name: metrics_pipeline + required: false + input: + type: string + title: Metrics pipeline name + description: >- + Which pipeline do you want to use to process the metrics this integration collects? + ref: core/v2/pipeline/metadata/name + refFilter: .labels.provider == "metrics" + resource_patches: + - resource: + api_version: core/v2 + type: CheckConfig + name: nginx-metrics + patches: + - path: /spec/command + op: replace + value: >- + nginx-check + --url {{ .annotations.metrics_nginx_url | default "[[ default_url ]]" }} + - path: /spec/subscriptions + op: replace + value: subscriptions + - path: /spec/pipelines/- + op: add + value: + api_version: core/v2 + type: Pipeline + name: "[[metrics_pipeline]]" + - path: /spec/pipelines/- + op: add + value: + api_version: core/v2 + type: Pipeline + name: "[[alerts_pipeline]]" + - path: /spec/pipelines/- + op: add + value: + api_version: core/v2 + type: Pipeline + name: "[[incidents_pipeline]]" + - path: /spec/output_metric_thresholds/0/thresholds/0/max + op: replace + value: "[[nginx_active_warn]]" + - path: /spec/output_metric_thresholds/1/thresholds/0/max + op: replace + value: "[[nginx_waiting_warn]]" + post_install: + - type: section + title: Success + - type: markdown + body: | + You enabled the NGINX Monitoring integration. + The `nginx-metrics` check will run for all Sensu agents with these subscriptions: [[subscriptions]]. +{{< /code >}} + +## Catalog repository example + +The repository that stores Sensu integrations must organize files in the following structure: + +{{< code text >}} +integrations/ +└── / + └── / + ├── img/ + │ ├── dashboard-1.gif + │ └── dashboard-2.png + ├── CHANGELOG.md + ├── README.md + ├── logo.png + ├── sensu-integration.yaml + └── sensu-resources.yaml + └── / + ├── img/ + │ ├── dashboard-1.gif + │ └── dashboard-2.png + ├── CHANGELOG.md + ├── README.md + ├── logo.png + ├── sensu-integration.yaml + └── sensu-resources.yaml +└── / + └── / + ├── img/ + │ ├── dashboard-1.gif + │ └── dashboard-2.png + ├── CHANGELOG.md + ├── README.md + ├── logo.png + ├── sensu-integration.yaml + └── sensu-resources.yaml +{{< /code >}} + +{{% notice note %}} +**NOTE**: In the context of catalog integration organization, "namespace" does not refer to the Sensu [role-based access control (RBAC) namespace](../../operations/control-access/namespaces/). +In catalogs, namespaces are categories for integrations. +For example, in the official Sensu Catalog, all integrations for AWS services are organized within the [`aws` namespace](https://github.com/sensu/catalog/tree/main/integrations/aws). +{{% /notice %}} + +File | Description +---- | ----------- +`img` | Images used in the integration README.md, such as screenshots of available dashboards. Image files must be GIF, JPEG, or PNG format. External image links are not supported. Optional. +`CHANGELOG.md` | Changelog for the integration. Not displayed in the web UI. Optional. +`README.md` | Help documentation for the integration, including an overview, setup steps, descriptions of the events and metrics the integration produces, and links to supplemental reference information. Sensu supports [GitHub-flavored Markdown][3] for integration READMEs. Required. +`logo.png` | Logo image to display in the web UI integration browser. Logo files must be PNG format. Required. +`sensu-integration.yaml` | Metadata for the integration, including title, description, prompts for configuration, patches for updating integration resources, and post-installation instructions. Integration metadata files must be in YAML format and must use the `.yaml` file extension (not `.yml`). Required. +`sensu-resources.yaml` | Sensu resources the integration will install, including checks, handlers, event filters, pipelines, and assets. Do not include [RBAC namespaces][4] in the resource definitions in the `sensu-resources.yaml` file. Resources files must be in YAML format and must use the `.yaml` file extension (not `.yml`). Required. + +## catalog-api command line interface tool + +{{% notice note %}} +**NOTE**: The catalog-api tool is an alpha feature and may include breaking changes. +{{% /notice %}} + +Sensu's [catalog-api][16] command line interface (CLI) tool generates the [static Catalog API][2] to convert integration files into static API content that you can host on any HTTP web service. +The Sensu web UI uses the generated API files to determine which integrations to display in the catalog. + +Use the catalog-api tool to [generate a local Catalog API][18] for testing as you develop new integrations and to [build and run a private catalog][17]. +Integration files must be stored in a repository that follows the required [organizational framework][15]. + +The catalog-api tool is written in Go. + +### catalog-api subcommands + +The catalog-api tool provides the following subcommands. + +{{< code text >}} +catalog-api catalog --help + +USAGE + catalog-api catalog [flags] [flags] + +SUBCOMMANDS + generate Generate a static catalog API + validate Validate a catalog directory and its integrations + server Serves static catalog API for development purposes + preview Serves static catalog API & preview catalog web application for development purposes + +FLAGS + -integrations-dir-name integrations path to the directory containing namespaced integrations + -log-level info log level of this command ([panic fatal error warn info debug trace]) + -repo-dir . path to the catalog repository +{{< /code >}} + +#### Generate subcommand + +The generate subcommand generates the contents of a catalog repository locally in a temporary directory, `/tmp/generated-api/`. + +Output for the generate subcommand lists the name, catalog namespace, source, and version number for all integration versions: + +{{< code text >}} +../catalog-api/catalog-api catalog generate + +10:40AM INF Found integration version name=ansible-tower-remediation namespace=ansible source=git tag=ansible/ansible-tower-remediation/20220223.0.0 version=20220223.0.0 +10:40AM INF Found integration version name=ansible-tower-remediation namespace=ansible source=git tag=ansible/ansible-tower-remediation/20220421.0.0 version=20220421.0.0 +10:40AM INF Found integration version name=aws-alb-monitoring namespace=aws source=git tag=aws/aws-alb-monitoring/20220421.0.0 version=20220421.0.0 +10:40AM INF Found integration version name=aws-ec2-monitoring namespace=aws source=git tag=aws/aws-ec2-monitoring/20220421.0.0 version=20220421.0.0 +... +10:40AM INF Found integration version name=timescaledb-metrics namespace=timescaledb source=git tag=timescaledb/timescaledb-metrics/20220308.0.0 version=20220308.0.0 +10:40AM INF Found integration version name=timescaledb-metrics namespace=timescaledb source=git tag=timescaledb/timescaledb-metrics/20220421.0.0 version=20220421.0.0 +10:40AM INF Found integration version name=wavefront-metrics namespace=wavefront source=git tag=wavefront/wavefront-metrics/20220421.0.0 version=20220421.0.0 +::set-output name=release-dir::/var/folders/60/cljzzn5n05d91t4x71jx9xzm0000gn/T/3556668713/release +{{< /code >}} + +The last line of output lists the local path for the generated catalog. + +##### Generate subcommand flags + +The catalog-api generate subcommand provides the following configuration flags: + +{{< code text >}} +catalog-api catalog generate --help + +USAGE + catalog-api catalog generate [flags] + +FLAGS + -integrations-dir-name integrations path to the directory containing namespaced integrations + -log-level info log level of this command ([panic fatal error warn info debug trace]) + -repo-dir . path to the catalog repository + -snapshot=false generate a catalog api for the current catalog branch + -temp-dir /var/folders/60/cljzzn5n05d91t4x71jx9xzm0000gn/T/ path to a temporary directory for generated files + -watch=false enter watch mode, which rebuilds on file change +{{< /code >}} + +#### Validate subcommand + +The validate subcommand confirms that all files in a catalog repository are organized properly. + +Output for the validate subcommand lists the name, catalog namespace, source, and version number for integrations found: + +{{< code text >}} +../catalog-api/catalog-api catalog validate + +10:37AM INF Found integration version name=ansible-tower-remediation namespace=ansible source=path version=99991231.0.0 +10:37AM INF Found integration version name=aws-alb-monitoring namespace=aws source=path version=99991231.0.0 +10:37AM INF Found integration version name=aws-ec2-monitoring namespace=aws source=path version=99991231.0.0 +... +10:37AM INF Found integration version name=wavefront-metrics namespace=wavefront source=path version=99991231.0.0 +{{< /code >}} + +##### Validate subcommand flags + +The catalog-api validate subcommand provides the following configuration flags: + +{{< code text >}} +catalog-api catalog validate --help + +USAGE + catalog-api catalog validate [flags] + +FLAGS + -integrations-dir-name integrations path to the directory containing namespaced integrations + -log-level info log level of this command ([panic fatal error warn info debug trace]) + -repo-dir . path to the catalog repository +{{< /code >}} + +#### Server subcommand + +The server subcommand starts a webserver to serve the JSON files the catalog-api tool generates. +To view your catalog in the Sensu web UI while running the server subcommand, you must also configure a Sensu backend and create a GlobalConfig resource to point to the webserver. + +The last line of the server subcommand response provides the address to use to view the content the catalog-api tool is serving the web UI in your browser. +For example: + +{{< code text >}} +10:00AM INF Found integration version name=ansible-tower-remediation namespace=ansible source=git tag=ansible/ansible-tower-remediation/20220223.0.0 version=20220223.0.0 +10:00AM INF Found integration version name=ansible-tower-remediation namespace=ansible source=git tag=ansible/ansible-tower-remediation/20220421.0.0 version=20220421.0.0 +10:00AM INF Found integration version name=aws-alb-monitoring namespace=aws source=git tag=aws/aws-alb-monitoring/20220421.0.0 version=20220421.0.0 +... +10:00AM INF Found integration version name=wavefront-metrics namespace=wavefront source=path version=99991231.0.0 +10:00AM INF API generated path=/var/folders/60/cljzzn5n05d91t4x71jx9xzm0000gn/T/2304694052 +10:00AM INF API server started address=:3003 +{{< /code >}} + +Visit your webserver address at port 3003 (for example, http://localhost:3003) to view the static Catalog API content that catalog-api is serving. + +Click the SHA-256 checksum to view the content for all catalog versions, including the integrations in each catalog version; the JSON definition for each integration version; the catalog repository files for each integration version; and a versions.json file that lists all versions for the integration: + +{{< figure src="/images/go/catalog_reference/server_checksum.gif" alt="View the API content for all catalog versions that catalog-api is serving in the browser" link="/images/go/catalog_reference/server_checksum.gif" target="_blank" >}} + +Click version.json to view the contents of the version.json file for the content that catalog-api is serving: + +{{< figure src="/images/go/catalog_reference/server_versions_json.gif" alt="View the version.json file for the content that catalog-api is serving in the browser" link="/images/go/catalog_reference/server_versions_json.gif" target="_blank" >}} + +##### Server subcommand flags + +The catalog-api server subcommand provides the following configuration flags: + +{{< code text >}} +catalog-api catalog server --help + +USAGE + catalog-api catalog server [flags] + +FLAGS + -integrations-dir-name integrations path to the directory containing namespaced integrations + -log-level info log level of this command ([panic fatal error warn info debug trace]) + -port 8083 port to use for dev server + -repo-dir . path to the catalog repository + -temp-dir /var/folders/60/cljzzn5n05d91t4x71jx9xzm0000gn/T/ path to a temporary directory for generated files + -watch=false enter watch mode, which rebuilds on file change + -without-snapshot=false generate a catalog api using tags only +{{< /code >}} + +##### Use the Sensu Catalog API server for integration development + +When you're developing integrations, it can be helpful to run the Sensu Catalog API server from your local environment so that you can preview integrations as you work. +To do this, use the server subcommand in the catalog-api command line tool. + +{{% notice note %}} +**NOTE**: Make sure you have a local Sensu instance running with access to the Sensu web UI. +{{% /notice %}} + +1. Clone the Sensu Catalog API repository and navigate to the local catalog-api repository: +{{< code shell >}} +git clone https://github.com/sensu/catalog-api && cd catalog-api +{{< /code >}} + +2. Build the catalog-api tool: +{{< code shell >}} +go build +{{< /code >}} + +3. Exit the local catalog-api repository: +{{< code shell >}} +cd .. +{{< /code >}} + +4. Clone the repository that stores your Sensu integrations. +This example uses Sensu's public integration repository: +{{< code shell >}} +git clone https://github.com/sensu/catalog +{{< /code >}} + +5. Navigate to your local copy of the repository that stores the Sensu integrations. +This example uses https://github.com/sensu/catalog, so the repository is `catalog`: +{{< code shell >}} +cd ../catalog +{{< /code >}} + +6. Run the catalog-api server subcommand: +This example uses https://github.com/sensu/catalog, so the repository is `catalog`: +{{< code shell >}} +../catalog-api/catalog-api catalog server --repo-dir . -watch +{{< /code >}} + + The `.` in the command tells Sensu to read the catalog contents from your local environment. + Use the `-watch` flag to reload the API as you save updates in integration files so that you can see them live in the Sensu web UI. + +7. Create a GlobalConfig resource that specifies a local URL for displaying the the private catalog in the Sensu web UI. +{{< language-toggle >}} + +{{< code shell "YML" >}} +cat << EOF | sensuctl create +--- +type: GlobalConfig +api_version: web/v1 +metadata: + name: private-catalog +spec: + always_show_local_cluster: true + catalog: + url: "https://127.0.0.1:3000" + release_version: version +EOF +{{< /code >}} + +{{< code shell "JSON" >}} +cat << EOF | sensuctl create +{ + "type": "GlobalConfig", + "api_version": "web/v1", + "metadata": { + "name": "private-catalog" + }, + "spec": { + "always_show_local_cluster": true, + "catalog": { + "url": "https://127.0.0.1:3000", + "release_version": "version" + } + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + +8. Navigate to the Catalog page in the Sensu web UI for your local instance (in this example, https://127.0.0.1:3000). +The Catalog page should include all of the integrations in your local repository and update automatically as you save local changes to your integration files. + +#### Preview subcommand + +The preview subcommand starts a webserver like the server subcommand but also serves a preview web UI that can communicate with the Sensu backend. +If you use the preview subcommand, you do not need to interact with the Sensu backend or create a GlobalConfig resource. + +The last line of the preview subcommand response provides the address to use to view the preview catalog in your browser. +For example: + +{{< code text >}} +9:57AM INF Found integration version name=ansible-tower-remediation namespace=ansible source=git tag=ansible/ansible-tower-remediation/20220223.0.0 version=20220223.0.0 +9:57AM INF Found integration version name=ansible-tower-remediation namespace=ansible source=git tag=ansible/ansible-tower-remediation/20220421.0.0 version=20220421.0.0 +9:57AM INF Found integration version name=aws-alb-monitoring namespace=aws source=git tag=aws/aws-alb-monitoring/20220421.0.0 version=20220421.0.0 +... +9:57AM INF Found integration version name=wavefront-metrics namespace=wavefront source=path version=99991231.0.0 +9:57AM INF API generated path=/var/folders/60/cljzzn5n05d91t4x71jx9xzm0000gn/T/2316699223 +9:57AM INF API server started address=:3003 +{{< /code >}} + +Visit your webserver address at port 3003 (for example, http://localhost:3003) to view a preview of the catalog in the Sensu web UI. + +##### Preview subcommand flags + +The catalog-api preview subcommand provides the following configuration flags: + +{{< code text >}} +catalog-api catalog preview --help + +USAGE + catalog-api catalog preview [flags] + +FLAGS + -api-url http://localhost:8080 host URL of Sensu installation; optional + -integrations-dir-name integrations path to the directory containing namespaced integrations + -log-level info log level of this command ([panic fatal error warn info debug trace]) + -port 3003 port to use for dev server + -repo-dir . path to the catalog repository + -temp-dir /var/folders/60/cljzzn5n05d91t4x71jx9xzm0000gn/T/ path to a temporary directory for generated files + -without-snapshot=false generate a catalog api using tags only + -without-watch=false enter watch mode, which rebuilds on file change +{{< /code >}} + +## Catalog tags and versions + +The catalog-api tool consumes and parses integration-specific git tags to manage and generate versioned integrations. +This makes it possible to give users access to earlier versions of integrations and hedge against regressions in individual integrations. + +For example, in the [official Sensu Catalog repository][30], two versions of the [Ansible Tower Remediation][31] are defined: + +{{< code text >}} +git tag --list |grep ansible-tower-remediation +ansible/ansible-tower-remediation/20220223.0.0 +ansible/ansible-tower-remediation/20220421.0.0 +{{< /code >}} + +Using these tags, the catalog-api tool would generate the following version structure, with both versions of the Ansible Tower Remediation integration: + +{{< code text >}} +tree /tmp/generated-api/ -L 7 +/tmp/generated-api/ +├── release +│ ├── 5029648381dff2426ea247147456b4f1227fd6d9050fa42f0660e67a218f8c87 +│ │ └── v1 +│ │ ├── ansible +│ │ │ ├── ansible-tower-remediation +│ │ │ │ ├── 20220223.0.0 +│ │ │ │ │ ├── CHANGELOG.md +│ │ │ │ │ ├── img +│ │ │ │ │ ├── logo.png +│ │ │ │ │ ├── README.md +│ │ │ │ │ └── sensu-resources.json +│ │ │ │ ├── 20220223.0.0.json +│ │ │ │ ├── 20220421.0.0 +│ │ │ │ │ ├── CHANGELOG.md +│ │ │ │ │ ├── img +│ │ │ │ │ ├── logo.png +│ │ │ │ │ ├── README.md +│ │ │ │ │ └── sensu-resources.json +│ │ │ │ ├── 20220421.0.0.json +│ │ │ │ └── versions.json +│ │ │ └── ansible-tower-remediation.json +{{< /code >}} + +### Catalog versions + +Catalog builds are versioned so that every previous iteration of the catalog is available. +You are not limited to providing only the most recent version of the catalog, and you can provide older versions as a fallback. + +The [catalog-api][32] tool generates builds into a checksum-based output directory structure. +The version.json file manages the path to the latest or production catalog API content and instructs the web UI to load catalog contents from the specified checksum directory. +When you run the catalog-api generate subcommand to generate the catalog, catalog-api creates the version.json file. + +The contents of a version.json file are similar to this example: + +{{< code text "JSON" >}} +{ + "release_sha256": "5029648381dff2426ea247147456b4f1227fd6d9050fa42f0660e67a218f8c87", + "last_updated": 1655840571 +} +{{< /code >}} + +If you make any changes to your integration files, the catalog-api tool will generate a new checksum directory. +To revert to an older build of the catalog, change the `release_sha256` in version.json to point to a different release directory. + +#### Generate version tags + +The [catalog-api][32] tool uses version tags to create versions of integrations and present them to users within the catalog. + +If you update an integration, the first step in publishing the updated integration is to generate a new tag for it: + +{{< code shell >}} +git tag //.0.0 +{{< /code >}} + +For example, to generate a new tag for an October 5, 2022 update to the [Ansible Tower Remediation][31] integration: + +{{< code shell >}} +git tag ansible/ansible-tower-remediation/20221005.0.0 +{{< /code >}} + +Commit your changes to git after adding the tag. +Then, run the catalog-api generate subcommand to generate a catalog that includes the tagged version: + +{{< code shell >}} +../catalog-api/catalog-api catalog generate +{{< /code >}} + +If you update the integration again on the same day, update the tag to `.0.1`. +To continue the Ansible Tower Remediation example: + +{{< code shell >}} +git tag ansible/ansible-tower-remediation/20221005.0.1 +{{< /code >}} + +Commit your changes to git. +The next time you run the catalog-api generate subcommand, it will generate a catalog that includes both tagged versions. + +## Private catalogs + +The [catalog-api][32] tool renders static HTTP API content that the Sensu web UI can consume. +This means you can create a private enterprise catalog of custom integrations and make it available to users in the Sensu web UI. + +You can use the official Sensu Catalog repository, https://github.com/sensu/catalog, as a starting point for building your own private catalog. +To do this, clone the repository with the `no-tags` flag to get a copy that does not include Sensu's tags for the existing integrations: + +{{< code shell >}} +git clone --no-tags https://github.com/sensu/catalog +{{< /code >}} + +The Catalog API defines integrations globally rather than by namespace. +When you create a private catalog, all integrations in your repository are available for all users across namespaces in the web UI. + +Read [Build a private catalog of Sensu integrations][17] for more information. + +## Integration specification + +### Top-level attributes + +api_version | +-------------|------ +description | Top-level attribute that specifies the Sensu API group and version. For integrations in this version of Sensu, the api_version should always be `catalog/v1`. +required | true +type | String +example | {{< code yml >}} +api_version: catalog/v1 +{{< /code >}} + +metadata | | +-------------|------ +description | Top-level scope that contains the integration's `name` and `namespace` information. +required | true +type | Map of key-value pairs +example | {{< code yml >}} +metadata: + namespace: nginx + name: nginx-monitoring +{{< /code >}} + +spec | +-------------|------ +description | Top-level map that includes integration [spec attributes][5]. +required | true +type | Map of key-value pairs +example | {{< code yml >}} +spec: + class: supported + provider: monitoring + display_name: NGINX Monitoring + short_description: Monitor NGINX service health and collect metrics + supported_platforms: + - darwin + - linux + - windows + tags: + - http + - nginx + - webserver + - service + contributors: + - "@nixwiz" + - "@calebhailey" + prompts: + - type: section + title: Configure NGINX URL and Monitoring Thresholds + - type: markdown + body: | + Specify the NGINX stub status URL and alerting thresholds for numbers of active and waiting connections. + - type: question + name: default_url + required: false + input: + type: string + title: NGINX stub status URL + description: Enter the NGINX stub_status URL + default: http://127.0.0.1:80/nginx_status + - type: question + name: nginx_active_warn + required: false + input: + type: integer + title: Maximum active connections + description: >- + Enter the maximum number of active connections to allow before sending a WARNING event (default is `300`) + default: 300 + - type: question + name: nginx_waiting_warn + required: false + input: + type: integer + title: Maximum waiting connections + description: >- + Enter the maximum number of waiting connections to allow before sending a WARNING event (default is `30`) + default: 30 + - type: section + title: Configure Sensu Subscriptions + - type: markdown + body: | + Specify the subscriptions for Sensu agents that should execute the `nginx-metrics` check. + - type: question + name: subscriptions + input: + type: array + items: + type: string + title: Sensu Subscriptions + ref: core/v2/entity/subscriptions + default: + - nginx + - type: section + title: Pipeline Configuration + - type: markdown + body: | + Name the [pipelines] you want to use to process NGINX Monitoring integration data. + [pipelines]: https://docs.sensu.io/sensu-go/latest/observability-pipeline/observe-process/pipelines/ + - type: question + name: alerts_pipeline + required: false + input: + type: string + title: Alert pipeline name + description: >- + Which pipeline do you want to use for alerts due to failures this integration detects? + ref: core/v2/pipeline/metadata/name + refFilter: .labels.provider == "alerts" + - type: question + name: incidents_pipeline + required: false + input: + type: string + title: Incident pipeline name + description: >- + Which pipeline do you want to use to process incidents due to failures this integration detects? + ref: core/v2/pipeline/metadata/name + refFilter: .labels.provider == "incidents" + - type: question + name: metrics_pipeline + required: false + input: + type: string + title: Metrics pipeline name + description: >- + Which pipeline do you want to use to process the metrics this integration collects? + ref: core/v2/pipeline/metadata/name + refFilter: .labels.provider == "metrics" + resource_patches: + - resource: + api_version: core/v2 + type: CheckConfig + name: nginx-metrics + patches: + - path: /spec/command + op: replace + value: >- + nginx-check + --url {{ .annotations.metrics_nginx_url | default "[[ default_url ]]" }} + - path: /spec/subscriptions + op: replace + value: subscriptions + - path: /spec/pipelines/- + op: add + value: + api_version: core/v2 + type: Pipeline + name: "[[metrics_pipeline]]" + - path: /spec/pipelines/- + op: add + value: + api_version: core/v2 + type: Pipeline + name: "[[alerts_pipeline]]" + - path: /spec/pipelines/- + op: add + value: + api_version: core/v2 + type: Pipeline + name: "[[incidents_pipeline]]" + - path: /spec/output_metric_thresholds/0/thresholds/0/max + op: replace + value: "[[nginx_active_warn]]" + - path: /spec/output_metric_thresholds/1/thresholds/0/max + op: replace + value: "[[nginx_waiting_warn]]" + post_install: + - type: section + title: Success + - type: markdown + body: | + You enabled the NGINX Monitoring integration. + The `nginx-metrics` check will run for all Sensu agents with these subscriptions: [[subscriptions]]. +{{< /code >}} + +type | +-------------|------ +description | Top-level attribute that specifies the resource type. For integrations, the type should always be `Integration`. +required | true +type | String +example | {{< code yml >}} +type: Integration +{{< /code >}} + +### Metadata attributes + +name | | +-------------|------ +description | Name for the integration that is used internally by Sensu. +required | true +type | String +example | {{< code yml >}} +name: nginx-monitoring +{{< /code >}} + +| namespace | | +-------------|------ +description | [Sensu RBAC namespace][4] that the integration belongs to. +required | false +type | String +example | {{< code yml >}} +namespace: nginx +{{< /code >}} + +### Spec attributes + +class | | +-------------|------ +description | Class to use for categorizing the integration in the web UI. +required | true +type | String +allowed values |
    • `community` for community-supported integrations
    • `supported` for Sensu-supported integrations
    • `enterprise` for Sensu-supported integrations that require a [commercial license][6]
    • `partner` for integrations supported by Sensu's third-party partners
    +example | {{< code yml >}} +class: community +{{< /code >}} + +contributors | | +-------------|------ +description | List of GitHub @usernames to display on integration detail pages in the web UI. +required | true +type | Array +example | {{< code yml >}} +contributors: + - "@nixwiz" + - "@calebhailey" +{{< /code >}} + +display_name | | +-------------|------ +description | Name to display for the integration in the web UI. +required | true +type | String +example | {{< code yml >}} +display_name: NGINX Monitoring +{{< /code >}} + +post_install | | +-------------|------ +description | Content to display for the final step in integration configuration.

    The post_install dialog is helpful for confirming successful installation and providing instructions for any further configuration an integration may require. If you do not include a post_install array in your integration definition, Sensu will display a default "Success" window.

    Read [Post install attributes][11] for more information. +required | false +type | Array +example | {{< code yml >}} +post_install: + - type: section + title: Success + - type: markdown + body: | + You enabled the NGINX Monitoring integration. + The `nginx-metrics` check will run for all Sensu agents with these subscriptions: [[subscriptions]]. +{{< /code >}} + + + +prompts | | +-------------|------ +description | Attributes for soliciting user-provided variable values to use in `resource_patches`. Read [Prompts attributes][10] for more information. +required | true +type | Map of key-value pairs +example | {{< code yml >}} +prompts: + - type: section + title: Configure NGINX URL and Monitoring Thresholds + - type: markdown + body: | + Specify the NGINX stub status URL and alerting thresholds for numbers of active and waiting connections. + - type: question + name: default_url + required: false + input: + type: string + title: NGINX stub status URL + description: Enter the NGINX stub_status URL + default: http://127.0.0.1:80/nginx_status + - type: question + name: nginx_active_warn + required: false + input: + type: integer + title: Maximum active connections + description: >- + Enter the maximum number of active connections to allow before sending a WARNING event (default is `300`) + default: 300 + - type: question + name: nginx_waiting_warn + required: false + input: + type: integer + title: Maximum waiting connections + description: >- + Enter the maximum number of waiting connections to allow before sending a WARNING event (default is `30`) + default: 30 + - type: section + title: Configure Sensu Subscriptions + - type: markdown + body: | + Specify the subscriptions for Sensu agents that should execute the `nginx-metrics` check. + - type: question + name: subscriptions + input: + type: array + items: + type: string + title: Sensu Subscriptions + ref: core/v2/entity/subscriptions + default: + - nginx + - type: section + title: Pipeline Configuration + - type: markdown + body: | + Name the [pipelines] you want to use to process NGINX Monitoring integration data. + [pipelines]: https://docs.sensu.io/sensu-go/latest/observability-pipeline/observe-process/pipelines/ + - type: question + name: alerts_pipeline + required: false + input: + type: string + title: Alert pipeline name + description: >- + Which pipeline do you want to use for alerts due to failures this integration detects? + ref: core/v2/pipeline/metadata/name + refFilter: .labels.provider == "alerts" + - type: question + name: incidents_pipeline + required: false + input: + type: string + title: Incident pipeline name + description: >- + Which pipeline do you want to use to process incidents due to failures this integration detects? + ref: core/v2/pipeline/metadata/name + refFilter: .labels.provider == "incidents" + - type: question + name: metrics_pipeline + required: false + input: + type: string + title: Metrics pipeline name + description: >- + Which pipeline do you want to use to process the metrics this integration collects? + ref: core/v2/pipeline/metadata/name + refFilter: .labels.provider == "metrics" +{{< /code >}} + +provider | | +-------------|------ +description | Integration function to use for categorizing the integration in the web UI. +required | true +type | String +allowed values | `alerts`, `deregistration`, `discovery`, `events`, `incidents`, `metrics`, `monitoring`, `remediation` +example | {{< code yml >}} +provider: monitoring +{{< /code >}} + +resource_patches | | +-------------|------ +description | Attributes that define how to apply changes to the integration resources in the `sensu-resources.yaml` file based on user responses to [prompts][22]. Read [Resource patches attributes][20] for more information. +required | true +type | Map of key-value pairs +example | {{< code yml >}} +resource_patches: + - resource: + api_version: core/v2 + type: CheckConfig + name: nginx-metrics + patches: + - path: /spec/command + op: replace + value: >- + nginx-check + --url {{ .annotations.metrics_nginx_url | default "[[ default_url ]]" }} + - path: /spec/subscriptions + op: replace + value: subscriptions + - path: /spec/pipelines/- + op: add + value: + api_version: core/v2 + type: Pipeline + name: "[[metrics_pipeline]]" + - path: /spec/pipelines/- + op: add + value: + api_version: core/v2 + type: Pipeline + name: "[[alerts_pipeline]]" + - path: /spec/pipelines/- + op: add + value: + api_version: core/v2 + type: Pipeline + name: "[[incidents_pipeline]]" + - path: /spec/output_metric_thresholds/0/thresholds/0/max + op: replace + value: "[[nginx_active_warn]]" + - path: /spec/output_metric_thresholds/1/thresholds/0/max + op: replace + value: "[[nginx_waiting_warn]]" +{{< /code >}} + +short_description | | +-------------|------ +description | Brief description of the integration to display in the web UI. +required | true +type | String +example | {{< code yml >}} +short_description: Monitor NGINX service health and collect metrics +{{< /code >}} + +supported_platforms | | +-------------|------ +description | Supported platforms for the integration. Used for checks only. +required | true +type | Array +example | {{< code yml >}} +supported_platforms: + - darwin + - linux + - windows +{{< /code >}} + +tags | | +-------------|------ +description | Keywords for the integration. Used for integration searches in the web UI. +required | true +type | Array +example | {{< code yml >}} +tags: + - http + - nginx + - webserver + - service +{{< /code >}} + +#### Post install attributes + + + +body | +-------------|------ +description | Markdown content to display in the integration post install dialog. If you specify [`type: markdown`][9], you must provide a `body` attribute. +required | false +type | String +example | {{< code yml >}} +body: | + You enabled the NGINX Monitoring integration. + The `nginx-metrics` check will run for all Sensu agents with these subscriptions: [[subscriptions]]. +{{< /code >}} + + + +title | +-------------|------ +description | Section title to display in the integration post install dialog. If you specify [`type: section`][9], you must provide a `title` attribute. +required | false +type | String +example | {{< code yml >}} +title: Success +{{< /code >}} + + + +type | +-------------|------ +description | Type of post install content to display.

    To configure a window of post install content, include a `type: section` attribute and a `type: markdown` attribute. For `type: section`, provide a [title][8]. For `type: markdown`, provide a [body][7].

    Each `type: section` attribute you add corresponds to one window of post install content; if you need more than one window of post install content, add another `type: section` attribute. +required | false +type | String +example | {{< code yml >}} +type: section +{{< /code >}} + +#### Prompts attributes + + + +body | +-------------|------ +description | Markdown content to display in a prompt. If you specify [`type: markdown`][9], you must include a `body` attribute. Body attributes are useful for providing instructions at the top of each prompt window. +required | false +type | String +example | {{< code yml >}} +body: | + Specify the NGINX stub status URL and alerting thresholds for numbers of active and waiting connections. +{{< /code >}} + +input | +-------------|------ +description | Configuration attributes for [`type: question`][12] prompts. Read [Input attributes][21] for more information. +required | false +type | Map of key-value pairs +example | {{< code yml >}} +input: + type: string + title: NGINX stub status URL + description: Enter the NGINX stub_status URL + default: http://127.0.0.1:80/nginx_status +{{< /code >}} + +name | +-------------|------ +description | Variable name for use as a reference in resource patches to substitute user input for a specific attribute's value in an integration resource. You can also interpolate integration variable names into string templates with double square brackets (e.g. `Hello, [[ team ]]!`). Used with [`type: question`][12] prompts. +required | false +type | String +example | {{< code yml >}} +name: default_url +{{< /code >}} + +required | +-------------|------ +description | If the associated prompt requires user input, `true`. Otherwise, `false`. Used with [`type: question`][12] prompts. +required | false +type | Boolean +example | {{< code yml >}} +attribute: +{{< /code >}} + + + +title | +-------------|------ +description | Section title to display in the integration prompts dialog. If you specify [`type: section`][9], you must provide a `title` attribute. +required | false +type | String +example | {{< code yml >}} +title: Configure NGINX URL and Monitoring Thresholds +{{< /code >}} + + + +type | +-------------|------ +description | Type of prompt to display.

    To configure a window of prompts, include a `type: section` attribute followed by a [title][12]. Within each window of prompts, use `type: question` attributes to collect user responses and `type: markdown` attributes to provide user instructions.

    Each `type: section` attribute you add corresponds to one window of prompts; if you need more than one window of prompts, add another `type: section` attribute. +required | false +type | String +example | {{< code yml >}} +type: section +{{< /code >}} + +#### Resource patches attributes + +patches | +-------------|------ +description | Updates to apply to the selected resource, in [JSON Patch][13] format.

    Variable substitution and templating are supported with `varname` references in double square brackets (for example, `Hello, [[varname]]`).

    If an individual operation fails, Sensu considers it optional and skips it.

    All patches must specify a `path`, `op` (operation), and `value`. Read [Patches attributes][24] for more information. +required | false +type | Map of key-value pairs +example | {{< code yml >}} +patches: + - path: /spec/command + op: replace + value: >- + nginx-check + --url {{ .annotations.metrics_nginx_url | default "[[ default_url ]]" }} + - path: /spec/subscriptions + op: replace + value: subscriptions +{{< /code >}} + +resource | +-------------|------ +description | Identification information for the Sensu API resource to patch. The resource must be included in the integration's `sensu-resources.yaml` file. Read [Resource attributes][23] for more information. +required | false +type | Map of key-value pairs +example | {{< code yml >}} +- resource: + api_version: core/v2 + type: CheckConfig + name: nginx-metrics +{{< /code >}} + +##### Input attributes + +default | +-------------|------ +description | Default value to use for the associated attribute if the user does not specify a value. +required | false +type | String +example | {{< code yml >}} +default: http://127.0.0.1:80/nginx_status +{{< /code >}} + +description | +-------------|------ +description | Description to display below the user input field. +required | false +type | String +example | {{< code yml >}} +description: Enter the NGINX stub_status URL +{{< /code >}} + +format | +---------------|------ +description | Format for the input value. Some display formats provide helpers that simplify user input. +required | false +type | String +allowed values | `cron`, `duration` `ecmascript-5.1`, `email`, `envvar`, `hostname`, `io.sensu.selector`, `ipv4`, `ipv6`, `tel`, `url`, `sh`, `sha-256`, `sha-512` +example | {{< code yml >}} +format: email +{{< /code >}} + + + +ref | +-------------|------ +description | Reference to a Sensu API resource in the format `///` (for example, `core/v2/pipelines/metadata/name` refers to the names of core/v2 pipelines resources).

    The referenced resources are presented to the user in a drop-down selector. Sensu captures the resource the user selects as the input value. +required | false +type | String +example | {{< code yml >}} +ref: core/v2/entity/subscriptions +{{< /code >}} + +refFilter | +-------------|------ +description | Filters to apply to Sensu API resource [references][19] in Sensu Query Expression (SQE) format. Sensu uses `refFilter` values to filter `ref` results. +required | false +type | String +example | {{< code yml >}} +refFilter: .labels.provider == "alerts" +{{< /code >}} + +title | +-------------|------ +description | Label to display above the user input field. +required | true +type | String +example | {{< code yml >}} +title: NGINX stub status URL +{{< /code >}} + +type | +---------------|------ +description | Type of input requested. +required | true +type | String +allowed values | `boolean`, `integer`, `string` +example | {{< code yml >}} +type: string +{{< /code >}} + +#### Patches attributes + +op | +-------------|------ +description | Patch operation to perform. +required | false +type | String +allowed values | `add`, `replace` +example | {{< code yml >}} +op: replace +{{< /code >}} + +path | +-------------|------ +description | Path for the attribute to patch within the specified Sensu resource. In [JSON Pointer][14] format, which supports array indexes such as `/spec/subscriptions/0`. Use `-` to insert values at the end of an array (for example, `/spec/subscriptions/-`). +required | false +type | String +example | {{< code yml >}} +path: /spec/subscriptions +{{< /code >}} + +value | +-------------|------ +description | Built-in or user-entered value to apply in the patch. The built-in value is `unique_id`, which randomly generates an 8-digit hexadecimal string value (e.g. 168c41a1). User-entered variables are represented by variable name references in double square brackets. +required | false +type | +example | {{< code yml >}} +value: [[ subscriptions ]] +{{< /code >}} + +##### Resource attributes + +api_version | +-------------|------ +description | Sensu API group and version for the resource to patch. +required | true +type | String +example | {{< code yml >}} +api_version: core/v2 +{{< /code >}} + +name | +-------------|------ +description | Name of the resource to patch. +required | true +type | String +example | {{< code yml >}} +name: nginx-metrics +{{< /code >}} + +type | +-------------|------ +description | Type of the resource to patch. +required | true +type | String +example | {{< code yml >}} +type: CheckConfig +{{< /code >}} + +## Resource limits + +There is no limit on the number of resources you can bundle into a single integration. +Each integration can include as many checks, event filters, handlers, and pipelines as you need to achieve your observability goals. +For example, you can develop a single host monitoring integration that installs all of the checks you want to run on every server. + +## Check guidelines + +For integrations that create checks, list the resource definitions in your `sensu-resources.yaml` file in the following order: + +1. CheckConfig +2. HookConfig +3. Secret +4. Asset + +The `sensu-integration.yaml` file for check resources should include at least one subscription, whether it is provided as a default or requested with a prompt. +Subscriptions should be named according to the check's function. +For example, a PostgreSQL monitoring check could include a subscription named `postgresql`. + +Use the YAML `>-` multiline block scalar syntax to wrap the check `command` value and make it easier to read. +For example: + +{{< code yml >}} +spec: + command: >- + check-disk-usage.rb + -w {{ .annotations.disk_usage_warning | default 85 }} + -c {{ .annotations.disk_usage_critical | default 95 }} +{{< /code >}} + +Use tunables like [tokens][25] in your check commands as needed, sourced from entity annotations (not labels) and with explicitly configured default values. + +Check resources should use [interval scheduling][26] with a minimum interval of 30 seconds. +Set check `timeout` to a non-zero value that is no greater than 50% of the interval. + +Prompts for check pipelines should use one of the following generic categories: + +- Alerts +- Incident management +- Metrics +- Events +- Deregistration +- Remediation + +## Pipeline guidelines + +For integrations that create pipelines, list the resource definitions in your `sensu-resources.yaml` file in the following order: + +1. Pipeline +2. Handler, SumoLogicMetricsHandler, and TCPStreamHandler +3. Filter +4. Mutator +5. Secret +6. Asset + +For alert and incident management pipelines, we recommend using the built-in [is_incident][27] and [not_silenced][28] event filters instead of custom event filters that are configured for specific use cases. + +## Asset guidelines + +Asset resources and their corresponding `runtime_assets` references in other Sensu resources must include an asset version reference in their resource name. +For example, `sensu/system-check:0.5.0`. + +Asset resources should include an organization or author as the namespace in the resource name. +For example, the official Sensu PagerDuty plugin hosted in the `sensu` organization on GitHub (sensu/sensu-pagerduty-handler) and published to under the `sensu` organization on Bonsai (sensu/sensu-pagerduty-handler) should be named `sensu/sensu-pagerduty-handler`. + +For integrations contributed to the official Sensu Catalog, asset resources in the `sensu-resources.yaml` file must refer to assets hosted on [Bonsai][29]. +Read [Build a private catalog of Sensu integrations][17] for information about using assets that are stored behind a firewall or are otherwise not publicly available. + + +[1]: ../sensu-catalog/ +[2]: ../catalog-api/ +[3]: https://github.github.com/gfm/ +[4]: ../../operations/control-access/namespaces/ +[5]: #spec-attributes +[6]: ../../commercial/ +[7]: #post-install-body +[8]: #post-install-title +[9]: #post-install-type +[10]: #prompts-attributes +[11]: #post-install-attributes +[12]: #prompts-type +[13]: https://jsonpatch.com/ +[14]: https://jsonpatch.com/#json-pointer +[15]: #catalog-repository-example +[16]: https://github.com/sensu/catalog-api +[17]: ../build-private-catalog/ +[18]: #use-the-sensu-catalog-api-server-for-integration-development +[19]: #input-ref +[20]: #resource-patches-attributes +[21]: #input-attributes +[22]: #integration-prompts +[23]: #resource-attributes +[24]: #patches-attributes +[25]: ../../observability-pipeline/observe-schedule/tokens/ +[26]: ../../observability-pipeline/observe-schedule/checks/#interval-scheduling +[27]: ../../observability-pipeline/observe-filter/filters/#built-in-filter-is_incident +[28]: ../../observability-pipeline/observe-filter/filters/#built-in-filter-not_silenced +[29]: https://bonsai.sensu.io/ +[30]: https://github.com/sensu/catalog +[31]: https://github.com/sensu/catalog/tree/main/integrations/ansible/ansible-tower-remediation +[32]: #catalog-api-command-line-interface-tool diff --git a/content/sensu-go/6.12/catalog/sensu-catalog.md b/content/sensu-go/6.12/catalog/sensu-catalog.md new file mode 100644 index 0000000000..8ad129de4e --- /dev/null +++ b/content/sensu-go/6.12/catalog/sensu-catalog.md @@ -0,0 +1,253 @@ +--- +title: "Configure integrations in the Sensu Catalog" +linkTitle: "Configure Integrations in the Sensu Catalog" +description: "Find, configure, and install powerful monitoring and observability integrations in the Sensu Catalog, Sensu's online marketplace." +weight: 20 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: catalog +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access the web UI and the Sensu Catalog in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../commercial/). +{{% /notice %}} + +{{% notice note %}} +**NOTE**: The Sensu Catalog is in public preview and is subject to change. +{{% /notice %}} + +The Sensu Catalog is an online marketplace for monitoring and observability integrations, from standard system checks and metrics collection to pipelines for sending Sensu data to third-party logging, remediation, and incident management services. + +The Sensu Catalog is part of the Sensu [web UI][21], so you can find, configure, and install integrations directly from your browser. + +{{< figure src="/images/go/sensu_catalog/catalog_homepage.png" alt="The Sensu Catalog page in the Sensu web UI" link="/images/go/sensu_catalog/catalog_homepage.png" target="_blank" >}} + +An integration combines a Sensu plugin with a dynamic runtime asset and the Sensu resource definitions that use the plugin. + +- The [plugin][1] provides the executable script or other program to power a Sensu check, handler, or mutator. +- The [dynamic runtime asset][20] is a shareable, reusable package that installs and deploys the plugin. + +Integrations provide the plugin and asset along with the recommended or minimum viable configuration and Sensu resources, integrating Sensu with different systems and services for collecting and processing observability data with a few clicks. + +Sensu Catalog integrations allow you to configure powerful real-time monitoring and observability for the systems you rely on. +All integrations are self-service and designed to help you scale up with fewer barriers. +Sensu curates, tests, and maintains the Catalog integrations, and installation follows a standardized process. + +## Find integrations + +Find integrations in the Sensu Catalog by browsing [alphabetized][16], [categorized][17], and [metadata-based][18] lists. +You can also [search][19] the Sensu Catalog based on integration metadata. + +### Browse the alphabetized list + +When the Catalog page loads in the Sensu web UI, all integrations are alphabetically listed by default. +To return to the alphabetized list at any time, click the **All** category in the Catalog page sidebar navigation menu: + +{{< figure src="/images/go/sensu_catalog/catalog_all_category.png" alt="All category for integrations on the Sensu Catalog page in the Sensu web UI" link="/images/go/sensu_catalog/catalog_all_category.png" target="_blank" >}} + +### Browse the categorized list + +The Catalog page sidebar navigation menu lists integrations in categories based on class and function. +Click a category to retrieve the associated integrations. + +{{< figure src="/images/go/sensu_catalog/catalog_menu.png" alt="Category-based menu for the Sensu Catalog page in the Sensu web UI" link="/images/go/sensu_catalog/catalog_menu.png" target="_blank" >}} + +Three categories describe the integration class: +- **Enterprise**: Integrations contributed by one of Sensu's third-party partners. +- **Supported**: Integrations that Sensu developed. Supported integrations may be [commercial features][7] that require a valid Sensu [license][8]. +- **Community**: Integrations contributed by members of the Sensu community. Community integrations are free and open-source. + +The rest of the categories are based on the integration's function, like cloud monitoring or automated remediation. + +### Browse a metadata-based list + +Each integration has associated metadata listed on the integration detail page: + +{{< figure src="/images/go/sensu_catalog/catalog_integration_metadata.png" alt="Example metadata for an integration in the Sensu web UI" link="/images/go/sensu_catalog/catalog_integration_metadata.png" target="_blank" >}} + +You can search the Sensu Catalog for integrations with particular `provider` or `tags` metadata from the Catalog main page: + +{{< figure src="/images/go/sensu_catalog/catalog_metadata_search.gif" alt="Sensu Catalog search for integrations with 'aws' in tags" link="/images/go/sensu_catalog/catalog_metadata_search.gif" target="_blank" >}} + +### Search for integrations + +The Sensu Catalog includes basic search using substring matching, as well as advanced searches based on integration metadata like display name and class. + +#### Catalog search operators + +Sensu Catalog search supports two set-based operators: + +| Operator | Description | Example | +| --------- | ------------------ | ---------------------- | +| `in` | Included in | `ansible in tags` +| `matches` | Substring matching | `display_name matches ansible` + +#### Catalog search metadata + +Search the Sensu Catalog integrations based on the following metadata: + +| Metadata type | Description +| ------------- | ------------------ +| `class` | Integration support category.

    Available values:
    - `community`: Supported by a Sensu community member
    - `enterprise`: Supported by Sensu; requires a [commercial license][7]
    - `partner`: Supported by a third-party company or service
    - `supported`: Supported by Sensu; no license required +| `display_name` | Integration name. +| `provider` | General function of the integration.

    Available values: `alerts`, `deregistration`, `discovery`, `events`, `incidents`, `metrics`, `monitoring`, `remediation`. +| `tags` | Descriptors added by the integration's creator. + +#### Quick search for integrations + +The Sensu Catalog quick search allows you to search without using any particular syntax. +Type your search term into the search field on the Catalog page of the web UI and press `Enter`. +Sensu will auto-complete a simple search statement for the resources on that page using substring matching: + +{{< figure src="/images/go/sensu_catalog/catalog_name_search.gif" alt="Sensu Catalog search for integrations by name" link="/images/go/sensu_catalog/catalog_name_search.gif" target="_blank" >}} + +## Get information about an integration + +In the Sensu Catalog, integrations are represented by tiles. +When you click an integration tile, the integration's detail page opens. +The detail page includes tabs for **README**, **CHANGELOG**, and **SENSU RESOURCES**. + +{{< figure src="/images/go/sensu_catalog/location_catalog_integration_info_tabs.png" alt="Location of README, CHANGELOG, and SENSU RESOURCES tabs for an integration in the Sensu Catalog" link="/images/go/sensu_catalog/location_catalog_integration_info_tabs.png" target="_blank" >}} + +The **README** tab contains detailed information about the integration, including an overview, supported dashboards, setup instructions, the plugins the integration requires, the metrics and alerts the integration generates, and links to reference information. +The **README** also describes any additional configuration needed to use the integration, like subscriptions to add to agent entities or secrets to create for sensitive information. + +The **CHANGELOG** tab lists the notable changes, improvements, and fixes for each version of the integration. + +The **SENSU RESOURCES** tab contains usable examples of all of the resource definitions you need to use the integration, including the plugin [asset][4], [secrets][5], [checks][2], [handlers][3], and [pipelines][6]. +Click the `yaml` or `json` buttons to select the format for each definition. + +{{% notice note %}} +**NOTE**: The SENSU RESOURCES tab lists example resource definitions that you must configure and install. +Use the **INSTALL** button to [configure and install the integration](#configure-and-install-an-integration) directly from your browser or copy the example definitions to configure and create with [sensuctl](../../sensuctl/create-manage-resources/) or the Sensu [API](../../api/). +{{% /notice %}} + +## Configure and install an integration + +When you find an integration you want to use, click the integration tile to open the detail page. +To configure and install an integration: + +1. Click **INSTALL** to open the configuration dialog. +The configuration dialog is a multi-page form with fields and prompts for collecting additional configuration attributes for the integration. +2. Type values in each attribute field in the dialog to configure the integration for your instance. +Use the **NEXT** and **BACK** buttons to navigate through configuration dialog pages as needed. +3. Review the resource definitions on the Summary page. +4. Click **APPLY** to save your configuration and create the integration resources. +5. Click **FINISH** on the confirmation page to close the configuration dialog. + +{{% notice note %}} +**NOTE**: When you click **APPLY** in step 4, Sensu creates all of the resources the integration requires. +Check resources are automatically published and will execute immediately. +{{% /notice %}} + +The configuration dialog suggests values for each attribute field. +These suggestions are collected from your existing resources and refined based on the specific requirements of the integration. +For example, if you are setting up a metrics collection integration that requires a pipeline, the dialog will only suggest existing metrics-compatible pipelines for that integration. +If you do not have any metrics-compatible pipelines, the dialog will not make suggestions for that attribute. + +The Summary page of the configuration dialog lists the definition for each resource that Sensu will create when you click **APPLY**. +These resource definitions include the attribute values you provided in the configuration dialog. +Click the dropdown arrows to review the resource definitions: + +{{< figure src="/images/go/sensu_catalog/catalog_integration_summary_definitions.gif" alt="Summary page of configuration dialog for a Sensu Catalog integration" link="/images/go/sensu_catalog/catalog_integration_summary_definitions.gif" target="_blank" >}} + +The resulting resource definitions represent Sensu's recommended configuration for the integration. + +## Use secrets in integrations + +The Sensu Catalog integrations are preconfigured to use Sensu's `Env` secrets provider for sensitive information the integrations might require, like passwords and API tokens. + +## Duplicate integrations and existing resources + +You can reuse the same integration as long as all resource definitions have unique names. + +When you install an integration, Sensu checks your existing resources before creating new resources. +If Sensu finds an existing resource with the same name, the configuration dialog will prompt you to either change the names of the existing resources or acknowledge that the new resources should overwrite the existing resources. + +If you want to keep the existing resources, use the [Sensu API][11] to change their names with PUT requests before you continue and create the new resources. +Otherwise, click **OVERWRITE** to replace the existing resources with the new resources. + +{{< figure src="/images/go/sensu_catalog/catalog_rename_overwrite_prompt.gif" alt="Summary page of configuration dialog with overwrite warning for a duplicate Sensu Catalog integration" link="/images/go/sensu_catalog/catalog_rename_overwrite_prompt.gif" target="_blank" >}} + +## View and manage your integrations + +After you install an integration, Sensu creates and publishes the integration resources within your current namespace. +The resources are listed on the configuration page for the resource type (checks, filters, handlers, or mutators). + +View and manage integration resources just like all of your other Sensu resources: in the [web UI][9], with [sensuctl][10], or with the Sensu [API][11]. + +## Reuse integration resources + +The integration definitions listed in the [**SENSU RESOURCES** tab][13] are usable, portable definitions for all of the resources you need to use the integration. +These definitions are universal [monitoring as code][15] templates: they do not include a namespace or the specific values you provide while [configuring and installing][14] the integration. + +## Contribute an integration + +The Sensu Catalog is an open marketplace, and you can contribute by sharing Sensu configurations. +For contributing guidelines and more information, visit the [Sensu Catalog GitHub repository][22]. + +## Disable the catalog + +For users that maintain control over how integrations are deployed in your environment, you may want to disable catalog via a [UI GlobalConfig definition][23] + + +{{< language-toggle >}} + +{{< code shell "YML" >}} +--- +type: GlobalConfig +api_version: web/v1 +metadata: + name: default +spec: + catalog: + disabled: true +EOF +{{< /code >}} + +{{< code shell "JSON" >}} +cat << EOF | sensuctl create +{ + "type": "GlobalConfig", + "api_version": "web/v1", + "metadata": { + "name": "default" + }, + "spec": { + "catalog": { + "disabled": true + } + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + + +[1]: ../../plugins/plugins/ +[2]: ../../observability-pipeline/observe-schedule/checks/ +[3]: ../../observability-pipeline/observe-process/handlers/ +[4]: ../../plugins/assets/ +[5]: ../../operations/manage-secrets/secrets/ +[6]: ../../observability-pipeline/observe-process/pipelines/ +[7]: ../../commercial/ +[8]: ../../operations/maintain-sensu/license/ +[9]: ../../web-ui/view-manage-resources/ +[10]: ../../sensuctl/create-manage-resources/ +[11]: ../../api/ +[13]: #get-information-about-an-integration +[14]: #configure-and-install-an-integration +[15]: ../../operations/monitoring-as-code/ +[16]: #browse-the-alphabetized-list +[17]: #browse-the-categorized-list +[18]: #browse-a-metadata-based-list +[19]: #search-for-integrations +[20]: ../../plugins/assets/ +[21]: ../../web-ui/ +[22]: https://github.com/sensu/catalog +[23]: ../build-private-catalog/#create-a-ui-globalconfig-definition diff --git a/content/sensu-go/6.12/commercial.md b/content/sensu-go/6.12/commercial.md new file mode 100644 index 0000000000..b0d8f06e88 --- /dev/null +++ b/content/sensu-go/6.12/commercial.md @@ -0,0 +1,137 @@ +--- +title: "Get started with commercial features" +linkTitle: "Commercial Features" +description: "Get started with commercial features in Sensu Go. Read this guide to learn about the latest commercial features. Contact our sales team for a free trial." +weight: -40 +version: "6.12" +menu: "sensu-go-6.12" +product: "Sensu Go" +--- + +Sensu Go offers commercial features designed for monitoring and observability at scale. +All commercial features are available in the official Sensu Go distribution, and you can use them for free [up to an entity limit of 100][7]. +If you have more than 100 entities, [contact the Sensu sales team][1] for a free trial. + +In addition to the [summary][25] on this page, we describe commercial features in detail throughout the documentation. +Watch for this notice to identify commercial features: + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../commercial/). +{{% /notice %}} + +## Commercial features in Sensu Go + +- **Integrate your Sensu observability pipeline with industry-standard tools** like EC2, Jira, ServiceNow, and Sumo Logic with [featured integrations][24] and [enterprise-tier dynamic runtime assets][11]. +Use the built-in [Sensu Plus][30] integration to transmit your observability data to Sumo Logic via the [HTTP Logs and Metrics Source][29]. +- **Find, configure, and install integrations directly in your browser** with the [Sensu Catalog][34], our online marketplace for monitoring and observability integrations. +- **Manage resources from your browser**: Use the Sensu [web UI][8] to manage events and entities and create, edit, and delete checks, handlers, mutators, silences, and event filters, with a single pane of glass view. +Create customized [global default settings][26] for page size and theme, [page-specific settings][27] for page size, order, and selector, and [sign-in messages][28]. +- **Control access with single sign-on (SSO) authentication** using [Lightweight Directory Access Protocol (LDAP), Active Directory (AD), or OpenID Connect 1.0 protocol (OIDC)][9]. +- **Maintain high-level visibility into the current health of your business services**. +Use [business service monitoring (BSM)][23] to monitor your system with a top-down approach that produces meaningful alerts, prevents alert fatigue, and helps you focus on your core business services. +- **Use mutual transport layer security (mTLS) authentication** to [provide two-way verification of your Sensu agents and backend connections][21]. +- **Protect your sensitive information** with [secrets management][22]. +Avoid exposing usernames, passwords, and access keys in your Sensu configuration with CyberArk Conjur, HashiCorp Vault, or Sensu's `Env` secrets provider. +- **Manage your monitoring resources across multiple data centers, cloud regions, or providers** and mirror changes to follower clusters with [federation][20]. +Federation affords visibility into the health of your infrastructure and services across multiple distinct Sensu instances within a single web UI. +- **Use powerful search capabilities** designed for large installations to search [Sensu API][4] responses, [sensuctl][5] outputs, and Sensu [web UI][6] views using custom labels and a wide range of resource attributes. +Build event filter expressions with [JavaScript execution functions][19]. +- **Achieve enterprise-scale event handling** for your Sensu instance with a [PostgreSQL event store][12]. +Access the PostgreSQL event datastore with the same Sensu web UI, API, and sensuctl processes as etcd-stored events. +Use [Sumo Logic metrics handlers][31] and [TCP stream handlers][32] to provide a persistent connection for transmitting Sensu observability metrics. +- **Get enterprise-class support**: Rest assured that with [Sensu support][13], help is available if you need it. +Our expert in-house team offers best-in-class support to get you up and running smoothly. + +Review a [complete comparison of OSS and commercial features][3]. + +## Contact us for a free trial + +Sensu's commercial features are [free for your first 100 entities][7]. +If your Sensu installation includes more than 100 entities, [contact the Sensu sales team][1] for a free trial of commercial features at scale in Sensu Go. + +Manage your Sensu account and contact support through [account.sensu.io][2]. + +## Get started with commercial features in Sensu Go + +If you haven't already, [install the Sensu Go backend, agent, and sensuctl tool][15] and [configure sensuctl][16]. + +You will need a commercial license if your Sensu installation includes more than 100 entities. +To download your commercial license file: + +1. Log in to your Sensu account at [account.sensu.io][2]. +2. Click **Download license**. + +{{% notice note %}} +**NOTE**: In some cases, you may need to click **Generate license** before you can download your license. +{{% /notice %}} + +{{< figure src="/images/go/commercial/license_download.png" alt="Screenshot of Sensu account license download" link="/images/go/commercial/license_download.png" target="_blank" >}} + +With the license file downloaded, you can use sensuctl to activate your commercial license: + +{{< code shell >}} +sensuctl create --file sensu_license.json +{{< /code >}} + +{{% notice note %}} +**NOTE**: For [clustered configurations](../operations/deploy-sensu/cluster-sensu), you only need to activate your license for one of the backends within the cluster. +{{% /notice %}} + +Use sensuctl to view your license details at any time: + +{{< code shell >}} +sensuctl license info +{{< /code >}} + +Users with permission to create or update licenses can also view license information in the Sensu [web UI][8] by pressing `CTRL .` to open the system information modal. + +These resources will help you use commercial features in Sensu Go: + +- [Configure mTLS authentication][21] for the Sensu agent. +- [Federate multiple Sensu instances][20] to gain single-pane-of-glass visibility into your infrastructure and services. +- [Install plugins with dynamic runtime assets][17] and use our complete catalog of [integrations][24]. +- Keep sensitive information like passwords and access tokens private with [secrets management][22]. +- [Set up and manage single sign-on (SSO) authentication providers][9]: Active Directory (AD), Lightweight Directory Access Protocol (LDAP), and OpenID Connect 1.0 protocol (OIDC). +- [Use the web UI][8] for a unified view of your events, entities, and configuration resources along with user-friendly tools, and create [customized page views][33]. +- [Monitor business services][23] and get high-level visibility into every component in your system. +- [Search in the web UI][6] or use powerful response filtering in [API][4] requests and [sensuctl][5] commands. +- Scale your monitoring and observability with Sensu's [enterprise datastore][12]. +- [Manage your Sensu commercial license][18] +- [Log in to your Sensu account][2] +- [Contact Sensu support][14] + + +[1]: https://sensu.io/contact?subject=contact-sales/ +[2]: https://account.sensu.io/ +[3]: https://sensu.io/features/compare +[4]: ../api/#response-filtering +[5]: ../sensuctl/filter-responses/ +[6]: ../web-ui/search/ +[7]: https://sensu.io/blog/one-year-of-sensu-go/ +[8]: ../web-ui/ +[9]: ../operations/control-access/sso/ +[11]: https://bonsai.sensu.io/assets?tiers%5B%5D=4/ +[12]: ../operations/deploy-sensu/scale-event-storage/ +[13]: https://sensu.io/support/ +[14]: https://account.sensu.io/support/ +[15]: ../operations/deploy-sensu/install-sensu/ +[16]: ../sensuctl/#first-time-setup-and-authentication +[17]: ../plugins/use-assets-to-install-plugins/ +[18]: ../operations/maintain-sensu/license/ +[19]: ../observability-pipeline/observe-filter/filters#build-event-filter-expressions-with-javascript-execution-functions +[20]: ../operations/deploy-sensu/use-federation/ +[21]: ../operations/deploy-sensu/secure-sensu/#optional-configure-sensu-agent-mtls-authentication +[22]: ../operations/manage-secrets/secrets-management/ +[23]: ../observability-pipeline/observe-schedule/business-service-monitoring/ +[24]: ../plugins/featured-integrations/ +[25]: #commercial-features-in-sensu-go +[26]: ../web-ui/webconfig-reference/#default-preferences-attributes +[27]: ../web-ui/webconfig-reference/#page-preferences-attributes +[28]: ../web-ui/webconfig-reference/#sign-in-message +[29]: https://help.sumologic.com/03Send-Data/Sources/02Sources-for-Hosted-Collectors/HTTP-Source +[30]: ../sensu-plus/ +[31]: ../observability-pipeline/observe-process/sumo-logic-metrics-handlers/ +[32]: ../observability-pipeline/observe-process/tcp-stream-handlers/ +[33]: ../web-ui/webconfig/ +[34]: ../catalog/sensu-catalog/ diff --git a/content/sensu-go/6.12/files/agent.yml b/content/sensu-go/6.12/files/agent.yml new file mode 100644 index 0000000000..deebb4078b --- /dev/null +++ b/content/sensu-go/6.12/files/agent.yml @@ -0,0 +1,88 @@ +--- +# Sensu agent configuration + + +## +# agent configuration +## +#name: "hostname" +#namespace: "default" +#subscriptions: +# - example +#labels: +# example_key: "example value" +#annotations: +# example/key: "example value" +#agent-managed-entity: false +#allow-list: /etc/sensu/check-allow-list.yaml +#assets-burst-limit: 100 +#assets-rate-limit: 1.39 +#backend-handshake-timeout: 15 +#backend-heartbeat-interval: 30 +#backend-heartbeat-timeout: 45 +#backend-url: +# - "ws://127.0.0.1:8081" +#cache-dir: "/var/cache/sensu/sensu-agent" +#config-file: "/etc/sensu/agent.yml" +#deregister: false +#deregistration-handler: "example_handler" +#detect-cloud-provider: false +#disable-assets: false +#keepalive-critical-timeout: 0 +#keepalive-handlers: +# - slack +# - email +#keepalive-interval: 20 +#keepalive-warning-timeout: 120 +log-level: "debug" # available log levels: panic, fatal, error, warn, info, debug +#user: "agent" +#password: "P@ssw0rd!" +#redact: +# - password +# - passwd +# - pass +# - api_key +# - api_token +# - access_key +# - secret_key +# - private_key +# - secret +#require-fips: false + + +## +# api configuration +## +#api-host: "127.0.0.1" +#api-port: 3031 +#disable-api: false +#events-burst-limit: 10 +#events-rate-limit: 10.0 + + +## +# socket configuration +## +#socket-host: "127.0.0.1" +#socket-port: 3030 +#disable-sockets: false + + +## +# statsd configuration +## +#statsd-disable: false +#statsd-event-handlers: +# - example_handler +#statsd-flush-interval: 10 +#statsd-metrics-host: "127.0.0.1" +#statsd-metrics-port: 8125 + + +## +# tls configuration +## +#cert-file: "/path/to/tls/agent.pem" +#trusted-ca-file: "/path/to/tls/ca.pem" +#key-file: "/path/to/tls/agent-key.pem" +#insecure-skip-tls-verify: false diff --git a/content/sensu-go/6.12/files/backend.yml b/content/sensu-go/6.12/files/backend.yml new file mode 100644 index 0000000000..a260998183 --- /dev/null +++ b/content/sensu-go/6.12/files/backend.yml @@ -0,0 +1,108 @@ +--- +# Sensu backend configuration + + +## +# backend configuration +## +#labels: +# example_key: "example value" +#annotations: +# example/key: "example value" +#assets-burst-limit: 100 +#assets-rate-limit: 1.39 +#agent-serve-wait-time: 0s +#agent-rate-limit: 100 +#cache-dir: "/var/cache/sensu/sensu-backend" +#config-file: "/etc/sensu/backend.yml" +#debug: false +#deregistration-handler: "example_handler" +log-level: "debug" #available log levels: panic, fatal, error, warn, info, debug, trace +#state-dir: "/var/lib/sensu/sensu-backend" +#require-fips: false +#eventd-buffer-size: 100 +#eventd-workers: 100 +#keepalived-buffer-size: 100 +#keepalived-workers: 100 +#pipelined-buffer-size: 100 +#pipelined-workers: 100 + + +## +# api configuration +## +#api-listen-address: "[::]:8080" #listen on all IPv4 and IPv6 addresses +#api-request-limit: 512000 +#api-serve-wait-time: 0s +#api-url: "http://localhost:8080" + + +## +# tls configuration +## +#agent-auth-cert-file: /path/to/tls/backend-1.pem +#agent-auth-crl-urls: http://localhost/CARoot.crl +#agent-auth-key-file: /path/to/tls/backend-1-key.pem +#agent-auth-trusted-ca-file: /path/to/tls/ca.pem +#agent-burst-limit: null +#agent-host: "[::]" #listen on all IPv4 and IPv6 addresses +#agent-port: 8081 +#agent-rate-limit: null +#cert-file: "/path/to/tls/backend-1.pem" +#insecure-skip-tls-verify: false +#jwt-private-key-file: /path/to/key/private.pem +#jwt-public-key-file: /path/to/key/public.pem +#key-file: "/path/to/tls/backend-1-key.pem" +#trusted-ca-file: "/path/to/tls/ca.pem" +#dashboard-cert-file: "/path/to/tls/separate-webui-cert.pem" +#dashboard-host: "[::]" +#dashboard-key-file: "/path/to/tls/separate-webui-key.pem" +#dashboard-port: 3000 + + +## +# etcd datastore configuration +## +#etcd-advertise-client-urls: +# - http://localhost:2378 +# - http://localhost:2379 +#etcd-cert-file: "/path/to/tls/backend-1.pem" +#etcd-cipher-suites: +# - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 +# - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 +# - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 +# - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 +# - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305 +# - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 +#etcd-client-cert-auth: false +#etcd-client-urls: +# - https://10.0.0.1:2379 +# - https://10.1.0.1:2379 +#etcd-discovery: +# - https://discovery.etcd.io/3e86b59982e49066c5d813af1c2e2579cbf573de +#etcd-discovery-srv: +# - example.org +#etcd-initial-advertise-peer-urls: +# - https://10.0.0.1:2380 +# - https://10.1.0.1:2380 +#etcd-initial-cluster: "backend-0=https://10.0.0.1:2380,backend-1=https://10.1.0.1:2380,backend-2=https://10.2.0.1:2380" +#etcd-initial-cluster-state: "new" +#etcd-initial-cluster-token: "unique_token_for_this_cluster" +#etcd-key-file: "/path/to/tls/backend-1-key.pem" +#etcd-listen-client-urls: +# - https://10.0.0.1:2379 +# - https://10.1.0.1:2379 +#etcd-listen-peer-urls: +# - https://10.0.0.1:2380 +# - https://10.1.0.1:2380 +#etcd-name: "backend-0" +#etcd-peer-cert-file: "/path/to/tls/backend-1.pem" +#etcd-peer-client-cert-auth: false +#etcd-peer-key-file: "/path/to/tls/backend-1-key.pem" +#etcd-peer-trusted-ca-file: "./ca.pem" +#etcd-trusted-ca-file: "./ca.pem" +#no-embed-etcd: false +#etcd-election-timeout: 3000 +#etcd-heartbeat-interval: 300 +#etcd-max-request-bytes: 1572864 +#etcd-quota-backend-bytes: 4294967296 diff --git a/content/sensu-go/6.12/files/sensu-plus-dashboard-config.json b/content/sensu-go/6.12/files/sensu-plus-dashboard-config.json new file mode 100644 index 0000000000..29c7a6d15b --- /dev/null +++ b/content/sensu-go/6.12/files/sensu-plus-dashboard-config.json @@ -0,0 +1,305 @@ +{ + "type": "FolderSyncDefinition", + "name": "Sensu", + "description": "Sensu+ Content", + "children": [ + { + "type": "DashboardV2SyncDefinition", + "name": "Sensu Entity Details", + "description": "Sensu Entity host metrics and events overview.", + "title": "Sensu Entity Details", + "rootPanel": null, + "theme": "Dark", + "topologyLabelMap": { + "data": {} + }, + "refreshInterval": 0, + "timeRange": { + "type": "BeginBoundedTimeRange", + "from": { + "type": "RelativeTimeRangeBoundary", + "relativeTime": "-3h" + }, + "to": null + }, + "layout": { + "layoutType": "Grid", + "layoutStructures": [ + { + "key": "panel07C8C24D85246949", + "structure": "{\"height\":8,\"width\":12,\"x\":0,\"y\":0}" + }, + { + "key": "panelPANE-679CCBDEA325EA46", + "structure": "{\"height\":8,\"width\":12,\"x\":12,\"y\":0}" + }, + { + "key": "panelPANE-07A5D753A4759B4B", + "structure": "{\"height\":6,\"width\":24,\"x\":0,\"y\":8}" + }, + { + "key": "panelPANE-2938F4DE9906EA46", + "structure": "{\"height\":15,\"width\":24,\"x\":0,\"y\":14}" + } + ] + }, + "panels": [ + { + "id": null, + "key": "panel07C8C24D85246949", + "title": "CPU Used", + "visualSettings": "{\"general\":{\"mode\":\"timeSeries\",\"type\":\"line\",\"displayType\":\"default\",\"markerSize\":5,\"lineDashType\":\"solid\",\"markerType\":\"none\",\"lineThickness\":1},\"title\":{\"fontSize\":14},\"axes\":{\"axisX\":{\"title\":\"\",\"titleFontSize\":11,\"labelFontSize\":10},\"axisY\":{\"title\":\"\",\"titleFontSize\":11,\"labelFontSize\":12,\"logarithmic\":false,\"unit\":{\"value\":\"%\",\"isCustom\":false}}},\"legend\":{\"enabled\":true,\"verticalAlign\":\"bottom\",\"fontSize\":12,\"maxHeight\":50,\"showAsTable\":false,\"wrap\":true},\"color\":{\"family\":\"Categorical Default\"},\"hiddenQueryKeys\":[\"B\"],\"overrides\":[{\"series\":[],\"queries\":[\"A\"],\"properties\":{\"name\":\"CPU Used ({{ entity }}/{{ cpu }})\"}}],\"series\":{}}", + "keepVisualSettingsConsistentWithParent": true, + "panelType": "SumoSearchPanel", + "queries": [ + { + "queryString": "metric=system_cpu_used entity={{ entity }} namespace={{ namespace }} | eval _value * .01", + "queryType": "Metrics", + "queryKey": "A", + "metricsQueryMode": "Advanced", + "metricsQueryData": null, + "tracesQueryData": null, + "parseMode": "Auto", + "timeSource": "Message" + } + ], + "description": "", + "timeRange": null, + "coloringRules": null, + "linkedDashboards": [] + }, + { + "id": null, + "key": "panelPANE-679CCBDEA325EA46", + "title": "Memory Used", + "visualSettings": "{\"general\":{\"mode\":\"timeSeries\",\"type\":\"line\",\"displayType\":\"default\",\"markerSize\":5,\"lineDashType\":\"solid\",\"markerType\":\"none\",\"lineThickness\":1},\"title\":{\"fontSize\":14},\"axes\":{\"axisX\":{\"title\":\"\",\"titleFontSize\":12,\"labelFontSize\":12},\"axisY\":{\"title\":\"\",\"titleFontSize\":12,\"labelFontSize\":12,\"logarithmic\":false,\"unit\":{\"value\":\"%\",\"isCustom\":false},\"unitDecimals\":0,\"hideLabels\":false}},\"legend\":{\"enabled\":true,\"verticalAlign\":\"bottom\",\"fontSize\":12,\"maxHeight\":50,\"showAsTable\":false,\"wrap\":true},\"color\":{\"family\":\"Categorical Default\"},\"series\":{},\"overrides\":[{\"series\":[],\"queries\":[\"A\"],\"properties\":{\"name\":\"Memory used ({{ entity }})\"}}]}", + "keepVisualSettingsConsistentWithParent": true, + "panelType": "SumoSearchPanel", + "queries": [ + { + "queryString": "metric=system_mem_used entity={{ entity }} namespace={{ namespace }} | eval _value * .01", + "queryType": "Metrics", + "queryKey": "A", + "metricsQueryMode": "Advanced", + "metricsQueryData": null, + "tracesQueryData": null, + "parseMode": "Auto", + "timeSource": "Message" + } + ], + "description": "", + "timeRange": null, + "coloringRules": null, + "linkedDashboards": [] + }, + { + "id": null, + "key": "panelPANE-07A5D753A4759B4B", + "title": "Sensu Events (per 5m interval)", + "visualSettings": "{\"title\":{\"fontSize\":14},\"axes\":{\"axisX\":{\"title\":\"Bucket (5m)\",\"titleFontSize\":12,\"labelFontSize\":12,\"hideLabels\":true},\"axisY\":{\"title\":\"Events\",\"titleFontSize\":12,\"labelFontSize\":12,\"logarithmic\":false,\"hideLabels\":false}},\"legend\":{\"enabled\":false,\"verticalAlign\":\"bottom\",\"fontSize\":12,\"maxHeight\":50,\"showAsTable\":false,\"wrap\":true},\"series\":{},\"general\":{\"type\":\"column\",\"displayType\":\"stacked\",\"fillOpacity\":0.75,\"mode\":\"timeSeries\"},\"color\":{\"family\":\"Categorical Light\"},\"overrides\":[{\"series\":[\"0\"],\"queries\":[],\"properties\":{\"color\":\"#6cae01\",\"name\":\"OK\"}},{\"series\":[\"1\"],\"queries\":[],\"properties\":{\"color\":\"#f2da73\",\"name\":\"WARNING\"}},{\"series\":[\"2\"],\"queries\":[],\"properties\":{\"color\":\"#bf2121\",\"name\":\"CRITICAL\"}}]}", + "keepVisualSettingsConsistentWithParent": true, + "panelType": "SumoSearchPanel", + "queries": [ + { + "queryString": "_sourceCategory=sensu-event {{ entity }} {{ namespace }}\n| json \"entity.metadata.name\",\"check.metadata.name\",\"check.status\",\"check.metadata.namespace\" as entity_name, check_name, check_status, check_namespace \n| where entity_name matches \"{{entity}}\" and check_namespace matches \"{{ namespace }}\"\n| timeslice 5m | count by _timeslice,check_status | transpose row _timeslice column check_status", + "queryType": "Logs", + "queryKey": "A", + "metricsQueryMode": null, + "metricsQueryData": null, + "tracesQueryData": null, + "parseMode": "Auto", + "timeSource": "Message" + } + ], + "description": "", + "timeRange": null, + "coloringRules": null, + "linkedDashboards": [] + }, + { + "id": null, + "key": "panelPANE-2938F4DE9906EA46", + "title": "Sensu Incidents", + "visualSettings": "{\"title\":{\"fontSize\":14},\"axes\":{\"axisX\":{\"titleFontSize\":12,\"labelFontSize\":12},\"axisY\":{\"titleFontSize\":12,\"labelFontSize\":12}},\"series\":{},\"general\":{\"type\":\"table\",\"displayType\":\"default\",\"paginationPageSize\":100,\"fontSize\":12,\"mode\":\"distribution\"},\"legend\":{\"enabled\":false}}", + "keepVisualSettingsConsistentWithParent": true, + "panelType": "SumoSearchPanel", + "queries": [ + { + "queryString": "_sourceCategory=sensu-event entity check output {{ entity }}\n| json \"check.last_ok\",\"entity.metadata.name\",\"check.metadata.name\", \"check.output\",\"check.state\",\"check.metadata.namespace\" as lastok,entity_name,check_name,output,state,check_namespace\n| where entity_name matches \"{{entity}}\" and check_namespace matches \"{{ namespace }}\"\n| max(_messagetime) as lasttime, first(output) as check_output, first(state) as check_state, first(lastok) as lastok by entity_name,check_name,check_namespace\n| where check_state != \"passing\"\n| order by +lastok,check_namespace,entity_name,check_name\n| formatDate(toLong(lastok*1000),\"yyyy-MM-dd HH:mm:ss\",\"UTC\") as LastOK_UTC\n| fields + lastok_UTC, check_namespace,entity_name,check_name,check_state,check_output\n", + "queryType": "Logs", + "queryKey": "A", + "metricsQueryMode": null, + "metricsQueryData": null, + "tracesQueryData": null, + "parseMode": "Auto", + "timeSource": "Message" + } + ], + "description": "", + "timeRange": null, + "coloringRules": null, + "linkedDashboards": [] + } + ], + "variables": [ + { + "id": null, + "name": "entity", + "displayName": "entity", + "defaultValue": "*", + "sourceDefinition": { + "variableSourceType": "MetadataVariableSourceDefinition", + "filter": "namespace={{namespace}}", + "key": "entity" + }, + "allowMultiSelect": false, + "includeAllOption": true, + "hideFromUI": false + }, + { + "id": null, + "name": "namespace", + "displayName": "namespace", + "defaultValue": "*", + "sourceDefinition": { + "variableSourceType": "MetadataVariableSourceDefinition", + "filter": "", + "key": "namespace" + }, + "allowMultiSelect": false, + "includeAllOption": true, + "hideFromUI": false + } + ], + "coloringRules": [] + }, + { + "type": "DashboardV2SyncDefinition", + "name": "Sensu Overview", + "description": "Overview of systems under management by Sensu Go (grouped by namespace and host OS)", + "title": "Sensu Overview", + "rootPanel": null, + "theme": "Dark", + "topologyLabelMap": { + "data": {} + }, + "refreshInterval": 0, + "timeRange": { + "type": "BeginBoundedTimeRange", + "from": { + "type": "RelativeTimeRangeBoundary", + "relativeTime": "-1h" + }, + "to": null + }, + "layout": { + "layoutType": "Grid", + "layoutStructures": [ + { + "key": "panelPANE-BBD3A0C69A056A4D", + "structure": "{\"height\":9,\"width\":24,\"x\":0,\"y\":9}" + }, + { + "key": "panel4030198BAD7CA940", + "structure": "{\"height\":9,\"width\":24,\"x\":0,\"y\":0}" + } + ] + }, + "panels": [ + { + "id": null, + "key": "panelPANE-BBD3A0C69A056A4D", + "title": "Entity Hostmap (CPU used by OS)", + "visualSettings": "{\"general\":{\"mode\":\"honeyComb\",\"type\":\"honeyComb\",\"displayType\":\"default\"},\"title\":{\"fontSize\":14},\"honeyComb\":{\"thresholds\":[{\"from\":0,\"to\":70,\"color\":\"#98ECA9\"},{\"from\":70,\"to\":85,\"color\":\"#F2DA73\"},{\"from\":85,\"to\":100,\"color\":\"#FFB5B5\"}],\"shape\":\"hexagon\",\"groupBy\":[{\"label\":\"os\",\"value\":\"os\"},{\"label\":\"platform\",\"value\":\"platform\"}],\"aggregationType\":\"latest\"},\"series\":{},\"overrides\":[{\"series\":[],\"queries\":[\"A\"],\"properties\":{}}],\"legend\":{\"enabled\":false}}", + "keepVisualSettingsConsistentWithParent": true, + "panelType": "SumoSearchPanel", + "queries": [ + { + "queryString": "metric=system_cpu_used cpu=cpu-total entity={{ entity }} namespace={{ namespace }} | avg by namespace,entity,os,platform", + "queryType": "Metrics", + "queryKey": "A", + "metricsQueryMode": "Advanced", + "metricsQueryData": null, + "tracesQueryData": null, + "parseMode": "Auto", + "timeSource": "Message" + } + ], + "description": "", + "timeRange": null, + "coloringRules": null, + "linkedDashboards": [ + { + "id": "siiult0ek2agirapE1HP7MdK8QA9z1sSWoAvprF1po1W5JWCJVL65HLJtV5M", + "relativePath": "../Sensu Entity Details", + "includeTimeRange": true, + "includeVariables": true + } + ] + }, + { + "id": null, + "key": "panel4030198BAD7CA940", + "title": "Entity Hostmap (CPU used by Sensu Namespace)", + "visualSettings": "{\"general\":{\"mode\":\"honeyComb\",\"type\":\"honeyComb\",\"displayType\":\"default\"},\"title\":{\"fontSize\":14},\"honeyComb\":{\"thresholds\":[{\"from\":0,\"to\":70,\"color\":\"#98ECA9\"},{\"from\":70,\"to\":85,\"color\":\"#F2DA73\"},{\"from\":85,\"to\":100,\"color\":\"#FFB5B5\"}],\"shape\":\"hexagon\",\"groupBy\":[{\"label\":\"namespace\",\"value\":\"namespace\"}],\"aggregationType\":\"latest\"},\"series\":{},\"overrides\":[{\"series\":[],\"queries\":[\"A\"],\"properties\":{}}],\"legend\":{\"enabled\":false}}", + "keepVisualSettingsConsistentWithParent": true, + "panelType": "SumoSearchPanel", + "queries": [ + { + "queryString": "metric=system_cpu_used cpu=cpu-total entity={{ entity }} namespace={{ namespace }} | avg by namespace,entity,os,platform", + "queryType": "Metrics", + "queryKey": "A", + "metricsQueryMode": "Advanced", + "metricsQueryData": null, + "tracesQueryData": null, + "parseMode": "Auto", + "timeSource": "Message" + } + ], + "description": "", + "timeRange": null, + "coloringRules": null, + "linkedDashboards": [ + { + "id": "siiult0ek2agirapE1HP7MdK8QA9z1sSWoAvprF1po1W5JWCJVL65HLJtV5M", + "relativePath": "../Sensu Entity Details", + "includeTimeRange": true, + "includeVariables": true + } + ] + } + ], + "variables": [ + { + "id": null, + "name": "entity", + "displayName": "entity", + "defaultValue": "*", + "sourceDefinition": { + "variableSourceType": "MetadataVariableSourceDefinition", + "filter": "namespace={{namespace}}", + "key": "entity" + }, + "allowMultiSelect": false, + "includeAllOption": true, + "hideFromUI": false + }, + { + "id": null, + "name": "namespace", + "displayName": "namespace", + "defaultValue": "*", + "sourceDefinition": { + "variableSourceType": "MetadataVariableSourceDefinition", + "filter": "", + "key": "namespace" + }, + "allowMultiSelect": false, + "includeAllOption": true, + "hideFromUI": false + } + ], + "coloringRules": [] + } + ] +} diff --git a/content/sensu-go/6.12/files/up_or_down_dashboard.json b/content/sensu-go/6.12/files/up_or_down_dashboard.json new file mode 100644 index 0000000000..ecd972353a --- /dev/null +++ b/content/sensu-go/6.12/files/up_or_down_dashboard.json @@ -0,0 +1,207 @@ +{ + "dashboard": { + "__inputs": [ + { + "name": "InfluxDB", + "label": "InfluxDB", + "description": "", + "type": "datasource", + "pluginId": "influxdb", + "pluginName": "InfluxDB" + } + ], + "__requires": [ + { + "type": "grafana", + "id": "grafana", + "name": "Grafana", + "version": "5.1.4" + }, + { + "type": "panel", + "id": "graph", + "name": "Graph", + "version": "5.0.0" + }, + { + "type": "datasource", + "id": "influxdb", + "name": "InfluxDB", + "version": "5.0.0" + } + ], + "annotations": { + "list": [ + { + "builtIn": 1, + "datasource": "-- Grafana --", + "enable": true, + "hide": true, + "iconColor": "rgba(0, 211, 255, 1)", + "name": "Annotations & Alerts", + "type": "dashboard" + } + ] + }, + "editable": true, + "gnetId": null, + "graphTooltip": 0, + "id": null, + "links": [], + "panels": [ + { + "aliasColors": {}, + "bars": false, + "dashLength": 10, + "dashes": false, + "datasource": "InfluxDB", + "fill": 1, + "gridPos": { + "h": 9, + "w": 12, + "x": 0, + "y": 0 + }, + "id": 2, + "legend": { + "avg": false, + "current": false, + "max": false, + "min": false, + "show": true, + "total": false, + "values": false + }, + "lines": true, + "linewidth": 1, + "links": [], + "nullPointMode": "null", + "percentage": false, + "pointradius": 5, + "points": false, + "renderer": "flot", + "seriesOverrides": [], + "spaceLength": 10, + "stack": false, + "steppedLine": false, + "targets": [ + { + "groupBy": [ + { + "params": [ + "$__interval" + ], + "type": "time" + }, + { + "params": [ + "none" + ], + "type": "fill" + } + ], + "measurement": "up", + "orderByTime": "ASC", + "policy": "default", + "refId": "A", + "resultFormat": "time_series", + "select": [ + [ + { + "params": [ + "value" + ], + "type": "field" + }, + { + "params": [], + "type": "mean" + } + ] + ], + "tags": [] + } + ], + "thresholds": [], + "timeFrom": null, + "timeShift": null, + "title": "Up or Down", + "tooltip": { + "shared": true, + "sort": 0, + "value_type": "individual" + }, + "type": "graph", + "xaxis": { + "buckets": null, + "mode": "time", + "name": null, + "show": true, + "values": [] + }, + "yaxes": [ + { + "format": "short", + "label": null, + "logBase": 1, + "max": null, + "min": null, + "show": true + }, + { + "format": "short", + "label": null, + "logBase": 1, + "max": null, + "min": null, + "show": true + } + ], + "yaxis": { + "align": false, + "alignLevel": null + } + } + ], + "refresh": "10s", + "schemaVersion": 16, + "style": "dark", + "tags": [], + "templating": { + "list": [] + }, + "time": { + "from": "now-15m", + "to": "now" + }, + "timepicker": { + "refresh_intervals": [ + "5s", + "10s", + "30s", + "1m", + "5m", + "15m", + "30m", + "1h", + "2h", + "1d" + ], + "time_options": [ + "5m", + "15m", + "1h", + "6h", + "12h", + "24h", + "2d", + "7d", + "30d" + ] + }, + "timezone": "", + "title": "Up or Down Sample 2", + "uid": "nb442Vsiz", + "version": 1 + } +} diff --git a/content/sensu-go/6.12/files/windows/agent.yml b/content/sensu-go/6.12/files/windows/agent.yml new file mode 100644 index 0000000000..c0c918cf1b --- /dev/null +++ b/content/sensu-go/6.12/files/windows/agent.yml @@ -0,0 +1,79 @@ +--- +# Sensu agent configuration for Windows + +## +# agent overview +## +#name: "hostname" +#namespace: "default" +#subscriptions: +# - example +#labels: +# example_key: "example value" +#annotations: +# example/key: "example value" + +## +# agent configuration +## +#backend-url: +# - "ws://127.0.0.1:8081" +#cache-dir: "c:/ProgramData/Sensu/sensu-agent/cache" +#config-file: "c:/ProgramData/Sensu/sensu-agent/config/agent.yml" +log-level: "debug" # available log levels: panic, fatal, error, warn, info, debug + +## +# api configuration +## +#api-host: "127.0.0.1" +#api-port: 3031 +#disable-api: false +#events-burst-limit: 10 +#events-rate-limit: 10.0 + +## +# authentication configuration +## +#user: "agent" +#password: "P@ssw0rd!" + +## +# monitoring configuration +## +#deregister: false +#deregistration-handler: "example_handler" +#keepalive-warning-timeout: 120 +#keepalive-interval: 20 + +## +# security configuration +## +#insecure-skip-tls-verify: false +#redact: +# - password +# - passwd +# - pass +# - api_key +# - api_token +# - access_key +# - secret_key +# - private_key +# - secret +#trusted-ca-file: "/path/to/trusted-certificate-authorities.pem" + +## +# socket configuration +## +#disable-sockets: false +#socket-host: "127.0.0.1" +#socket-port: 3030 + +## +# statsd configuration +## +#statsd-disable: false +#statsd-event-handlers: +# - example_handler +#statsd-flush-interval: 10 +#statsd-metrics-host: "127.0.0.1" +#statsd-metrics-port: 8125 diff --git a/content/sensu-go/6.12/get-started.md b/content/sensu-go/6.12/get-started.md new file mode 100644 index 0000000000..3a4efae72e --- /dev/null +++ b/content/sensu-go/6.12/get-started.md @@ -0,0 +1,75 @@ +--- +title: "Get started with Sensu" +linkTitle: "Get Started with Sensu" +description: "Automate observability workflows and gain deep visibility into cloud environments with Sensu, the industry-leading solution for multi-cloud monitoring at scale." +version: "6.12" +weight: -70 +product: "Sensu Go" +menu: "sensu-go-6.12" +--- + +[Sensu Go][2] is the flexible observability pipeline designed for container-based and multi-cloud infrastructures. + +Sensu is available as packages, Docker images, and binary-only distributions. +You can [install the commercial distribution][15] or [build Sensu from source][16]. + +## Install the commercial distribution of Sensu Go + +Sensu's [supported platforms][20] include Debian- and RHEL-family distributions and Windows. + +- [**Install Sensu Go**][2] with a commercial package and get started for free +- Learn about Sensu's [commercial features][3] — all commercial features are available for free in the packaged Sensu Go distribution up to an entity limit of 100 +- Find the [Sensu architecture][18] that best meets your needs +- Discover, configure, and install monitoring and observability integrations in the [Sensu Catalog][23] and explore hundreds of dynamic runtime assets for deploying plugins in [Bonsai][6], the Sensu asset hub +- [Migrate from Sensu Core and Sensu Enterprise to Sensu Go][13] + +## Learn Sensu + +Watch this video for a 10-minute introduction to Sensu Go: + +{{< youtube uyj3qFjq58g >}} + +We recommend these resources for learning more about Sensu: + +- Follow the [self-guided Sensu Go Workshop][12] and create your first [observability pipeline][22] +- Try a [live demo of the Sensu web UI][1] +- Sign up for our step-by-step [Learn Sensu email course][21] +- Join the [Sensu Community Forum on Discourse][8] + +## Explore monitoring at scale with Sensu Go + +Sensu offers support packages for Sensu Go as well as commercial licenses designed for monitoring at scale. + +- [Contact the sales team][4] for a personalized demo and free trial of commercial features at scale +- [Activate your Sensu commercial license][5] + +## Build Sensu from source (OSS) + +Sensu Go's core is open source software, freely available under an MIT License. + +- [Compare OSS and commercial features][14] +- [Visit Sensu Go on GitHub][10] +- [Build from source][11] + + +[1]: ../learn/demo/ +[2]: ../operations/deploy-sensu/install-sensu/ +[3]: ../commercial +[4]: https://sensu.io/contact?subject=contact-sales +[5]: ../commercial/#get-started-with-commercial-features-in-sensu-go +[6]: https://bonsai.sensu.io/ +[8]: https://discourse.sensu.io/ +[9]: ../operations/maintain-sensu/license/ +[10]: https://github.com/sensu/sensu-go/ +[11]: https://www.github.com/sensu/sensu-go/blob/main/README.md#building-from-source +[12]: https://github.com/sensu/sensu-go-workshop#overview +[13]: ../operations/maintain-sensu/migrate/ +[14]: https://sensu.io/features/compare +[15]: #install-the-commercial-distribution-of-sensu-go +[16]: #build-sensu-from-source-oss +[17]: #explore-monitoring-at-scale-with-sensu-go +[18]: ../operations/deploy-sensu/deployment-architecture/#common-sensu-architectures +[20]: ../platforms/ +[21]: https://sensu.io/learn +[22]: ../observability-pipeline/ +[23]: ../catalog/sensu-catalog/ diff --git a/content/sensu-go/6.12/guides/_index.md b/content/sensu-go/6.12/guides/_index.md new file mode 100644 index 0000000000..18c50cfc29 --- /dev/null +++ b/content/sensu-go/6.12/guides/_index.md @@ -0,0 +1,18 @@ +--- +title: "Guides Index" +linkTitle: "Guides Index" +description: "Read Sensu's guides to learn how to configure Sensu to reduce alert fatigue, export metrics, and more." +product: "Sensu Go" +version: "6.12" +weight: 30 +layout: "single" +toc: false +menu: + sensu-go-6.12: + identifier: guide +--- + +This index links to every guide in the Sensu documentation. +Guides describe how to configure Sensu to complete specific observability tasks and workflows to monitor server resources, route alerts and reduce alert fatigue, export metrics, plan maintenance windows, and more, with examples and step-by-step walkthroughs. + +{{< guidetypeListing >}} diff --git a/content/sensu-go/6.12/learn/_index.md b/content/sensu-go/6.12/learn/_index.md new file mode 100644 index 0000000000..a73a567d03 --- /dev/null +++ b/content/sensu-go/6.12/learn/_index.md @@ -0,0 +1,50 @@ +--- +title: "Learn Sensu" +description: "Learn Sensu with a self-guided workshop, live web UI demo, and a glossary of Sensu terminology with links to in-depth documentation." +product: "Sensu Go" +version: "6.12" +weight: 120 +layout: "single" +toc: true +menu: + sensu-go-6.12: + identifier: learn-sensu +--- + +The Learn Sensu category includes tools to help you understand and start using Sensu, the industry-leading observability pipeline for multi-cloud monitoring, consolidating monitoring tools, and filling observability gaps at scale. + +## Concepts and terminology + +If you're new to Sensu, start with a basic review of Sensu [concepts and terminology][1], which includes definitions and links to relevant reference documentation for more in-depth information. + +To visualize how Sensu concepts work together in the observability pipeline, [take the tour][6] — follow the `Next` buttons on each page. + +## Sensu Go workshop + +The [Sensu Go workshop][4] is a collection of resources designed to help you learn Sensu: + +- Interactive lessons designed for self-guided learning. +- Detailed instructions for Linux, macOS, and Windows workstations. +- A local sandbox environment for use with the workshop (via Docker Compose or Vagrant) + +Additional workshop materials are available for advanced use cases, including instructor-led workshops with a multi-tenant sandbox environment and alternative sandbox environments based on popular Sensu reference architectures like InfluxDB, TimescaleDB, Elasticsearch, and Prometheus. + +[Follow the workshop lessons][4] to build your first observability workflow with Sensu. + +## Live demo + +Explore a [live demo][3] of the Sensu web UI: view the Entities page to learn what Sensu is monitoring, the Events page for the latest observability events, and the Checks page for active service and metric checks. +The live demo also gives you a chance to try commands with [sensuctl][8], the Sensu command line tool. + +## Monitor containers and applications + +Follow the instructions for [Getting Started with Sensu Go on Kubernetes][5] to deploy a Sensu cluster and an example application (NGINX) into Kubernetes with a Sensu agent sidecar. +You’ll also learn to use sensuctl to configure Nagios-style monitoring checks to monitor the example application with a Sensu sidecar. + + +[1]: concepts-terminology/ +[3]: demo/ +[4]: https://github.com/sensu/sensu-go-workshop#overview +[5]: https://github.com/sensu/sensu-k8s-quick-start +[6]: ../observability-pipeline/ +[8]: ../sensuctl/ diff --git a/content/sensu-go/6.12/learn/concepts-terminology.md b/content/sensu-go/6.12/learn/concepts-terminology.md new file mode 100644 index 0000000000..d745164863 --- /dev/null +++ b/content/sensu-go/6.12/learn/concepts-terminology.md @@ -0,0 +1,158 @@ +--- +title: "Glossary of Sensu concepts and terminology" +linkTitle: "Concepts and Terminology" +description: "Use this glossary to get familiar with Sensu concepts and terminology. Each summary includes a link to more in-depth information." +weight: 10 +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: learn-sensu +--- + +## Agent +A lightweight client that runs on the infrastructure components you want to monitor. +Agents self-register with the backend, send keepalive messages, and execute monitoring checks. +Each agent belongs to one or more subscriptions that determine which checks the agent runs. +An agent can run checks on the entity it’s installed on or connect to a remote proxy entity. +[Read more about the Sensu agent][1]. + +## Asset +An executable that a check, handler, or mutator can specify as a dependency. +Dynamic runtime assets must be a tar archive (optionally gzipped) with scripts or executables within a bin folder. +At runtime, the backend or agent installs required assets using the specified URL. +Dynamic runtime assets let you manage runtime dependencies without using configuration management tools. +[Read more about dynamic runtime assets][4]. + +## Backend +A flexible, scalable observability pipeline. +The Sensu backend processes observation data (events) using filters, mutators, and handlers. +It maintains configuration files, stores recent observation data, and schedules monitoring checks. +You can interact with the backend using the API, command line, and web UI interfaces. +[Read more about the Sensu backend][2]. + +## Business service monitoring (BSM) +A feature that provides high-level visibility into the current health of your business services. +An example business service is a company website, which might require several individual elements to have OK status for the website to function (e.g. webservers, an inventory database, and a shopping cart). +With business service monitoring (BSM), you could create a current status page for the company website that displays the website’s overall status at a glance. + +BSM requires two resources that work together to achieve top-down monitoring: service components and rule templates. +Service components are the elements that make up your business services. +Rule templates define the monitoring rules that produce events for service components based on customized evaluation expressions. + +[Read more about BSM][19], [rule templates][20], and [service components][21]. + +## Catalog +The Sensu Catalog is an element of the Sensu web UI where you can find and install monitoring and observability integrations. +An integration combines a Sensu plugin with a dynamic runtime asset and the Sensu resource definitions that use the plugin. +The Sensu Catalog includes integrations for standard system checks and metrics collection as well as pipelines for sending Sensu data to third-party logging, remediation, and incident management services. +[Read more about the Sensu Catalog][24]. + +## Check +A recurring check the agent runs to determine the state of a system component or collect metrics. +The backend is responsible for storing check definitions, scheduling checks, and processing observation data (events). +Check definitions specify the command to be executed, an interval for execution, one or more subscriptions, and one or more handlers to process the resulting event data. +[Read more about checks][3]. + +## Entity +Infrastructure components that you want to monitor. +Each entity runs an agent that executes checks and creates events. +Events can be tied to the entity where the agent runs or a proxy entity that the agent checks remotely. +[Read more about entities][7]. + +## Event +A representation of the state of an infrastructure component at a point in time. +The Sensu backend uses events to power the observability pipeline. +Observation data in events include the result of a check or metric (or both), the executing agent, and a timestamp. +[Read more about events][8]. + +## Event filter +Logical expressions that handlers evaluate before processing observability events. +Event filters can instruct handlers to allow or deny matching events based on day, time, namespace, or any attribute in the observation data (event). +[Read more about event filters][9]. + +## Handler +A component of the observability pipeline that acts on events. +Handlers can send observability data to an executable (or handler plugin), a TCP socket, or a UDP socket. +[Read more about handlers][10]. + +## Hook +A command the agent executes in response to a check result *before* creating an observability event. +Hooks create context-rich events by gathering relevant information based on check status. +[Read more about hooks][5]. + +## Mutator +An executable the backend runs prior to a handler to transform observation data (events). +[Read more about mutators][11]. + +## Pipeline +Resources composed of observation event processing workflows made up of filters, mutators, and handlers. +Instead of specifying filters and mutators in handler definitions, you can specify all three in a single pipeline workflow. +[Read more about pipelines][23]. + +## Plugin +Executables designed to work with Sensu observation data (events) either as a check, mutator, or handler plugin. +You can write your own check executables in Go, Ruby, Python, and more, or use one of more than 200 plugins shared by the Sensu community. +[Read more about plugins][6]. + +## Proxy entities +Components of your infrastructure that can’t run the agent locally (like a network switch or a website) but still need to be monitored. +Agents create events with information about the proxy entity in place of the local entity when running checks with a specified proxy entity ID. +[Read more about proxy entities][12]. + +## Role-based access control (RBAC) +Sensu’s local user management system. +RBAC lets you manage users and permissions with namespaces, users, roles, and role bindings. +[Read more about RBAC][13]. + +## Resources +Objects within Sensu that you can use to specify access permissions in Sensu roles and cluster roles. +Resources can be specific to a namespace (like checks and handlers) or cluster-wide (like users and cluster roles). +[Read more about resources][18]. + +## Sensuctl +The Sensu command line tool that lets you interact with the backend. +You can use sensuctl to create checks, view events, create users, manage clusters, and more. +[Read more about sensuctl][14]. + +## Silencing +Entries that allow you to suppress execution of event handlers on an ad-hoc basis. +Use silencing to schedule maintenance without being overloaded with alerts. +[Read more about silencing][17]. + +## Subscriptions +Attributes used to indicate which entities will execute which checks. +For Sensu to execute a check, the check definition must include a subscription that matches the subscription of at least one Sensu entity. +Subscriptions allow you to configure check requests in a one-to-many model for entire groups or subgroups of entities rather than a traditional one-to-one mapping of configured hosts or observability checks. +[Read more about subscriptions][22]. + +## Token +A placeholder in a check definition that the agent replaces with local information before executing the check. +Tokens let you fine-tune check attributes (like thresholds) on a per-entity level while reusing the check definition. +[Read more about tokens][16]. + + +[1]: ../../observability-pipeline/observe-schedule/agent/ +[2]: ../../observability-pipeline/observe-schedule/backend/ +[3]: ../../observability-pipeline/observe-schedule/checks/ +[4]: ../../plugins/assets/ +[5]: ../../observability-pipeline/observe-schedule/hooks/ +[6]: ../../plugins/install-plugins/ +[7]: ../../observability-pipeline/observe-entities/entities/ +[8]: ../../observability-pipeline/observe-events/events/ +[9]: ../../observability-pipeline/observe-filter/filters/ +[10]: ../../observability-pipeline/observe-process/handlers/ +[11]: ../../observability-pipeline/observe-transform/mutators/ +[12]: ../../observability-pipeline/observe-entities/#proxy-entities +[13]: ../../operations/control-access/rbac/ +[14]: ../../sensuctl/ +[15]: ../../observability-pipeline/observe-schedule/checks/#subdue-attributes +[16]: ../../observability-pipeline/observe-schedule/tokens/ +[17]: ../../observability-pipeline/observe-process/silencing/ +[18]: ../../operations/control-access/rbac#resources +[19]: ../../observability-pipeline/observe-schedule/business-service-monitoring/ +[20]: ../../observability-pipeline/observe-schedule/rule-templates/ +[21]: ../../observability-pipeline/observe-schedule/service-components/ +[22]: ../../observability-pipeline/observe-schedule/subscriptions/ +[23]: ../../observability-pipeline/observe-process/pipelines/ +[24]: ../../catalog/sensu-catalog/ diff --git a/content/sensu-go/6.12/learn/demo.md b/content/sensu-go/6.12/learn/demo.md new file mode 100644 index 0000000000..bdccbbe990 --- /dev/null +++ b/content/sensu-go/6.12/learn/demo.md @@ -0,0 +1,48 @@ +--- +title: "Live demonstration of Sensu" +linkTitle: "Live Demo" +description: "Explore the Sensu web UI and sensuctl command line tool with a live demo. View entities, observability events, and active service and metric checks." +version: "6.12" +weight: 30 +toc: false +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: learn-sensu +--- + +Try a live demo of the Sensu web UI. +Log in with username `guest` and password `i<3sensu`. + +Explore the Entities page to learn what Sensu is monitoring, the Events page for the latest observability events, and the Checks page for active service and metric checks. + +You can also use the demo to try out sensuctl, the Sensu command line tool. +First, [install sensuctl][1] on your workstation. +Then, configure sensuctl to connect to the demo. + +Run `sensuctl configure` and enter the following information: + +{{< code text >}} +Authentication method: username/password +Sensu Backend API URL: https://caviar.tf.sensu.io:8080 +Namespace: default +Preferred output format: tabular +Username: guest +Password: i<3sensu +{{< /code >}} + +With sensuctl configured, to view the latest observability events, run: + +{{< code shell >}} +sensuctl event list +{{< /code >}} + +Read the [sensuctl documentation][2] to get started using sensuctl. + +## About the demo + +The Caviar project shown in the demo monitors the [Sensu docs site][3] using a licensed Sensu cluster of three backends. + +[1]: ../../operations/deploy-sensu/install-sensu#install-sensuctl +[2]: ../../sensuctl/ +[3]: https://docs.sensu.io/ diff --git a/content/sensu-go/6.12/observability-pipeline/_index.md b/content/sensu-go/6.12/observability-pipeline/_index.md new file mode 100644 index 0000000000..1ff835e2e0 --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/_index.md @@ -0,0 +1,41 @@ +--- +title: "Sensu Observability Pipeline" +linkTitle: "Observability Pipeline" +description: "Learn how Sensu's observability pipeline works as a flexible, automated tool to give you visibility into every part of your organization's infrastructure." +product: "Sensu Go" +version: "6.12" +weight: 10 +layout: "single" +toc: false +menu: + sensu-go-6.12: + identifier: observability-pipeline +--- + +Sensu's observability pipeline is a flexible, automated tool that gives you visibility into every part of your organization's infrastructure. + +The Sensu [agent][1] is a lightweight process that runs on the infrastructure components you want to observe. +Each agent is represented in Sensu as an [entity][2]. +The Sensu [backend][1] schedules [checks][3] for agents to run on your infrastructure. +Agents receive check execution requests based on the agent subscriptions you specify. + +The agent runs these checks on your infrastructure to gather observation data about your networking, compute resources, applications, and more. +[Events][3] contain the observation data that your checks gather, which might include entity status, metrics, or both, depending on your needs and configuration. + +The agent sends events to the backend, which [filters][5], [transforms][6], and [processes][7] the data in your events with event filters, mutators, and handlers. + +Sensu's observability pipeline delivers contextualized information and deeper insights so you can take targeted actions. +For example, Sensu can send entity status data in an email, Slack, or PagerDuty alert and transport metrics to storage in your Graphite, InfluxDB, or Prometheus databases. + +** or click any element in the pipeline to jump to it.** + + + + + +[1]: observe-schedule/ +[2]: observe-entities/ +[3]: observe-schedule/ +[5]: observe-filter/ +[6]: observe-transform/ +[7]: observe-process/ diff --git a/content/sensu-go/6.12/observability-pipeline/observe-entities/_index.md b/content/sensu-go/6.12/observability-pipeline/observe-entities/_index.md new file mode 100644 index 0000000000..02fbcbc807 --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-entities/_index.md @@ -0,0 +1,361 @@ +--- +title: "Entities" +linkTitle: "Entities" +description: "Learn about Sensu entities, which represent anything that needs to be monitored in your environment, from server hardware to serverless functions." +product: "Sensu Go" +version: "6.12" +weight: 10 +layout: "single" +toc: true +menu: + sensu-go-6.12: + parent: observability-pipeline + identifier: observe-entities +--- + + + + +** or click any element in the pipeline to jump to it.** + +An [entity][6] represents anything that needs to be observed or monitored, such as a server, container, or network switch, including the full range of infrastructure, runtime, and application types that compose a complete monitoring environment (from server hardware to serverless functions). +Sensu calls parts of an infrastructure "entities." + +An entity provides the context for observation data in events — what and where the event is from. +The check and entity names associated with an event determine the event's uniqueness. +Entities can also contain system information like the hostname, operating system, platform, and version. + +There are four types of Sensu entities: agent, proxy, service, and backend entities. + +## Agent entities + +Agent entities are monitoring agents that are installed and run on every system that needs to be observed or monitored. +The agent entity registers the system with the Sensu backend service, sends keepalive messages (the Sensu heartbeat mechanism), and executes observability checks. + +Each entity is a member of one or more `subscriptions`: a list of roles and responsibilities assigned to the agent entity (for example, a webserver or a database). +Sensu entities "subscribe" to (or watch for) check requests published by the Sensu backend (via the Sensu transport), execute the corresponding requests locally, and publish the results of the check back to the transport (to be processed by a Sensu backend). + +This example shows an agent entity resource definition: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Entity +api_version: core/v2 +metadata: + name: i-424242 +spec: + deregister: false + deregistration: {} + entity_class: agent + last_seen: 0 + sensu_agent_version: 1.0.0 + subscriptions: + - web + system: + cloud_provider: "" + libc_type: "" + network: + interfaces: null + processes: null + vm_role: "" + vm_system: "" +{{< /code >}} + +{{< code json >}} +{ + "type": "Entity", + "api_version": "core/v2", + "metadata": { + "name": "i-424242" + }, + "spec": { + "deregister": false, + "deregistration": { + }, + "entity_class": "agent", + "last_seen": 0, + "sensu_agent_version": "1.0.0", + "subscriptions": [ + "web" + ], + "system": { + "cloud_provider": "", + "libc_type": "", + "network": { + "interfaces": null + }, + "processes": null, + "vm_role": "", + "vm_system": "" + } + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Proxy entities + +Proxy entities [formerly known as proxy clients or just-in-time (JIT) clients] allow Sensu to monitor external resources on systems where you cannot install a Sensu agent, like a network switch or website. + +Proxy entities are dynamically created when an entity does not already exist for a check result. +In this case, Sensu uses the [`proxy_entity_name`][7] defined in the check to create proxy entities for external resources. + +This example shows a proxy entity resource definition: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Entity +api_version: core/v2 +metadata: + labels: + proxy_type: website + sensu.io/managed_by: sensuctl + url: https://docs.sensu.io + name: sensu-docs + namespace: default +spec: + deregister: false + deregistration: {} + entity_class: proxy + last_seen: 0 + sensu_agent_version: "" + subscriptions: null + system: + cloud_provider: "" + libc_type: "" + network: + interfaces: null + processes: null + vm_role: "" + vm_system: "" +{{< /code >}} + +{{< code json >}} +{ + "type": "Entity", + "api_version": "core/v2", + "metadata": { + "labels": { + "proxy_type": "website", + "sensu.io/managed_by": "sensuctl", + "url": "https://docs.sensu.io" + }, + "name": "sensu-docs", + "namespace": "default" + }, + "spec": { + "deregister": false, + "deregistration": { + }, + "entity_class": "proxy", + "last_seen": 0, + "sensu_agent_version": "", + "subscriptions": null, + "system": { + "cloud_provider": "", + "libc_type": "", + "network": { + "interfaces": null + }, + "processes": null, + "vm_role": "", + "vm_system": "" + } + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Service entities + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access business service monitoring (BSM), including service entities, in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../commercial/). +{{% /notice %}} + +{{% notice note %}} +**NOTE**: Business service monitoring (BSM) is in public preview and is subject to change. +{{% /notice %}} + +A service entity represents a business service in [business service monitoring (BSM)][8]. +Sensu processes service entity events just like events generated for agent and proxy entities. +You can also use service entities for proxy check requests and events. + +This example shows a service entity resource definition: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Entity +api_version: core/v2 +metadata: + name: postgresql +spec: + entity_class: service +{{< /code >}} + +{{< code json >}} +{ + "type": "Entity", + "api_version": "core/v2", + "metadata": { + "name": "postgresql" + }, + "spec": { + "entity_class": "service" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Backend entities + +A backend entity represents a Sensu backend. +Sensu automatically creates a backend entity for each backend when it is started and populates the entity with the backend's system information. +Users cannot manually create backend entities. + +Backends use their own entities to generate events due to error conditions like unavailable components and services. + +This example shows a backend entity resource definition: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Entity +api_version: core/v2 +metadata: + name: 6b6264feda40 + namespace: sensu-system +spec: + deregister: false + deregistration: {} + entity_class: backend + last_seen: 0 + sensu_agent_version: '' + subscriptions: null + system: + arch: amd64 + cloud_provider: '' + hostname: 6b6264feda40 + libc_type: glibc + network: + interfaces: + - addresses: + - 127.0.0.1/8 + name: lo + - addresses: null + name: tunl0 + - addresses: null + name: ip6tnl0 + - addresses: + - 172.18.0.4/16 + mac: 02:42:ac:12:00:04 + name: eth0 + os: linux + platform: redhat + platform_family: rhel + platform_version: '7.9' + processes: null + vm_role: guest + vm_system: '' +{{< /code >}} + +{{< code json >}} +{ + "type": "Entity", + "api_version": "core/v2", + "metadata": { + "name": "6b6264feda40", + "namespace": "sensu-system" + }, + "spec": { + "deregister": false, + "deregistration": { + }, + "entity_class": "backend", + "last_seen": 0, + "sensu_agent_version": "", + "subscriptions": null, + "system": { + "arch": "amd64", + "cloud_provider": "", + "hostname": "6b6264feda40", + "libc_type": "glibc", + "network": { + "interfaces": [ + { + "addresses": [ + "127.0.0.1/8" + ], + "name": "lo" + }, + { + "addresses": null, + "name": "tunl0" + }, + { + "addresses": null, + "name": "ip6tnl0" + }, + { + "addresses": [ + "172.18.0.4/16" + ], + "mac": "02:42:ac:12:00:04", + "name": "eth0" + } + ] + }, + "os": "linux", + "platform": "redhat", + "platform_family": "rhel", + "platform_version": "7.9", + "processes": null, + "vm_role": "guest", + "vm_system": "" + } + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Usage limits + +Sensu's usage limits are based on entities. + +The free limit is 100 entities. +All [commercial features][2] are available for free in the packaged Sensu Go distribution for up to 100 entities. +If your Sensu instance includes more than 100 entities, [contact us][3] to learn how to upgrade your installation and increase your limit. Read the [announcement on our blog][4] for more information about our usage policy. + +Commercial licenses may include an entity limit and entity class limits: + +- Entity limit: the maximum number of entities of all classes your license includes. +Agent, proxy, and service entities count toward the overall entity limit. +- Entity class limits: the maximum number of a specific class of entities (agent, proxy, or service) that your license includes. + +For example, if your license has an entity limit of 10,000 and an agent entity class limit of 3,000, you cannot run more than 10,000 entities (agent and proxy) total. +At the same time, you cannot run more than 3,000 agents. +If you use only 1,500 agent entities, you can have 8,500 proxy entities before you reach the overall entity limit of 10,000. + +If you have permission to create or update licenses, you will see messages in sensuctl and the web UI when you approach your licensed entity or entity class limit, as well as when you exceed these limits. +You can also use sensuctl or the /license API to [view your overall entity count and limit][5]. + + +[1]: monitor-external-resources/ +[2]: ../../commercial/ +[3]: https://sensu.io/contact +[4]: https://sensu.io/blog/one-year-of-sensu-go +[5]: ../../operations/maintain-sensu/license/#view-entity-count-and-entity-limit +[6]: entities/ +[7]: ../observe-schedule/checks/#proxy-entity-name-attribute +[8]: ../observe-schedule/business-service-monitoring/ diff --git a/content/sensu-go/6.12/observability-pipeline/observe-entities/auto-register-deregister.md b/content/sensu-go/6.12/observability-pipeline/observe-entities/auto-register-deregister.md new file mode 100644 index 0000000000..f9a40c3307 --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-entities/auto-register-deregister.md @@ -0,0 +1,227 @@ +--- +title: "Automatically register and deregister entities" +linkTitle: "Auto-register and Deregister Entities" +guide_title: "Automatically register and deregister entities" +type: "guide" +description: "Keep your Sensu instance up-to-date with automatic agent discovery, registration, and deregistration for infrastructure components and services." +weight: 20 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: observe-entities +--- + +Sensu uses the [publish/subscribe pattern of communication][2], which allows automated registration and deregistration of ephemeral systems. +Sensu agents automatically discover and register infrastructure components and the services running on them. +At the same time, when an agent process stops, the Sensu backend can automatically create and process a deregistration event. + +Automatic registration and deregistration keeps your Sensu instance up-to-date and avoids unnecessary process load, especially in containerized environments where containers routinely come online and offline. +You'll see observability event data soon after an agent entity comes online, and you won't receive stale events or alerts for entities that no longer exist. + +You can also configure [handlers][4] that take specific actions based on agent registration and deregistration, such as updating external [configuration management databases (CMDBs)][3]. + +## Discovery and registration + +Sensu agents automatically discover and register infrastructure components and the services running on them. + +{{% notice note %}} +**NOTE**: Automatic discovery is not supported for proxy entities because they cannot run a Sensu agent. +Use the [core/v2/events API](../../../api/core/events/) to send manual keepalive events for proxy entities. +{{% /notice %}} + +### Registration events + +When an agent comes online, it sends its first [keepalive event][5]. +When a Sensu backend processes a keepalive event for an agent whose name is not already listed in the Sensu agent registry, Sensu automatically registers the agent. +The Sensu backend stores the entity registry, which you can view by running `sensuctl entity list`. + +If you configure a [handler][4] named `registration`, the Sensu backend will create and process a registration event for that handler to process. +The `registration` handler must reference the name of a handler or handler set that you want to execute for every registration event. + +{{% notice warning %}} +**WARNING**: Registration events are not stored in the event registry, so they are not accessible via the Sensu API. +However, all registration events are logged in the [Sensu backend log](../../observe-schedule/backend/#event-logging). +{{% /notice %}} + +### Registration handler example + +You can use registration event handlers to execute one-time handlers for new Sensu agents based on registration events. + +For example, suppose you want to update the ServiceNow CMDB table that contains your Sensu entity inventory upon every registration event. +First, configure a handler that uses the [sensu/sensu-servicenow-handler][6] dynamic runtime asset and the `--cmdb-registration` argument: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Handler +api_version: core/v2 +metadata: + name: servicenow_cmdb +spec: + type: pipe + command: sensu-servicenow-handler --cmdb-registration + runtime_assets: + - sensu/sensu-servicenow-handler:3.0.0 + env_vars: + - SERVICENOW_URL=https://example.servicenow.com + secrets: + - name: SERVICENOW_USERNAME + secret: servicenow_username + - name: SERVICENOW_PASSWORD + secret: servicenow_password + timeout: 10 +{{< /code >}} + +{{< code json >}} +{ + "type": "Handler", + "api_version": "core/v2", + "metadata": { + "name": "servicenow_cmdb" + }, + "spec": { + "type": "pipe", + "command": "sensu-servicenow-handler --cmdb-registration", + "runtime_assets": [ + "sensu/sensu-servicenow-handler:3.0.0" + ], + "env_vars": [ + "SERVICENOW_URL=https://example.servicenow.com" + ], + "secrets": [ + { + "name": "SERVICENOW_USERNAME", + "secret": "servicenow_username" + }, + { + "name": "SERVICENOW_PASSWORD", + "secret": "servicenow_password" + } + ], + "timeout": 10 + } +} +{{< /code >}} + +{{< /language-toggle >}} + +Then, create a `registration` handler that references the `servicenow_cmdb` handler: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Handler +api_version: core/v2 +metadata: + name: registration +spec: + handlers: + - servicenow_cmdb + type: pipe +{{< /code >}} + +{{< code json >}} +{ + "type": "Handler", + "api_version": "core/v2", + "metadata": { + "name": "registration" + }, + "spec": { + "handlers": [ + "servicenow_cmdb" + ], + "type": "pipe" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +Now the Sensu backend will execute the referenced `servicenow-cmdb` handler for every registration event. +The *referenced* handler can send registration event alerts to any service, such as [Sumo Logic][7] or [PagerDuty][8], as long as it is listed within a handler named `registration`. + +{{% notice protip %}} +**PRO TIP**: Use a [handler set](../../observe-process/handlers#handler-sets) to execute multiple handlers in response to registration events. +{{% /notice %}} + +## Deregistration + +Just like Sensu can automatically register new agent entities when they send their first [keepalive][5], Sensu can automatically deregister agent entities when they shut down and the agent process stops. + +To enable automatic deregistration, set the agent [`deregister`][9] attribute to `true`. +When the Sensu agent process stops and the agent stops sending keepalive messages, the Sensu backend can deregister the corresponding entity without any further action. + +{{% notice note %}} +**NOTE**: Deregistration is supported for [agent entities](../../observe-entities/#agent-entities) that have sent at least one keepalive. +Deregistration is **not** supported for [proxy entities](../../observe-entities/#proxy-entities), which do not send keepalives, and the backend does not automatically create and process deregistration events for proxy entities. +{{% /notice %}} + +### Deregistration events + +As with registration events, the Sensu backend can create and process a deregistration event when a Sensu agent process stops. + +When an agent exceeds its keepalive timeout setting, the backends will generate a keepalive failure for that agent and create an event on its behalf. +If you set the agent [`deregister`][9] attribute to `true`, when keepalive failure occurs, Sensu will delete the agent entity from the entity registry and send a deregistration event through the event pipeline. + +To take action based on deregistration events, you must also specify a handler to use for deregistration events in the agent or backend configuration: + +- To use a deregistration handler for a specific agent, set the [**agent** deregistration-handler attribute][10]. +- To use a deregistration handler to process all deregistration events for all agents, set the [**backend** deregistration-handler attribute][11]. + +The agent `deregistration-handler` attribute overrides the backend `deregistration-handler` attribute. +In other words, if you specify both an agent and backend deregistration handler, Sensu will use only the handler specified in the agent configuration. + +{{% notice note %}} +**NOTE**: If you set the agent [`deregister`](../../observe-schedule/agent/#ephemeral-agent-configuration) attribute to `true`, when a Sensu agent process stops, the Sensu backend will deregister the corresponding entity.

    +Deregistration prevents and clears alerts for failing keepalives for agent entities — the backend does not distinguish between intentional shutdown and failure. +As a result, if you set the deregister flag to `true` and an agent process stops for any reason, you will not receive alerts for keepalive events in the web UI.

    +If you want to receive alerts for failing keepalives, set the agent `deregister` attribute to `false`. +{{% /notice %}} + +### Deregistration handler example + +Just like registration events, deregistration events can trigger a one-time handler that performs an action like updating an external CMDB or ephemeral infrastructures. +In fact, you can use the [`servicenow_cmdb` handler][1] to update the ServiceNow CMDB table that contains your Sensu entity inventory, this time based on every deregistration event. + +To specify `servicenow_cmdb` as the agent deregistration handler: + +{{< language-toggle >}} + +{{< code shell "Command line" >}} +sensu-agent start --deregistration-handler servicenow_cmdb +{{< /code >}} + +{{< code shell "Configuration file" >}} +deregistration-handler: servicenow_cmdb +{{< /code >}} + +{{< /language-toggle >}} + + +## Next steps + +The [Sensu Catalog][12] includes the [Platform Discovery][13] integration, which detects the agent operating system and platform information and updates the agent's subscriptions accordingly. +This integration allows you to deploy agents with a single subscription and use the auto-discovery check to add system-based subscriptions automatically. + +Follow [Create limited service accounts][14] to automatically remove AWS EC2 instances that are not in a pending or running state. + + +[1]: #registration-handler-example +[2]: https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern +[3]: https://en.wikipedia.org/wiki/Configuration_management_database +[4]: ../../observe-process/handlers/ +[5]: ../../observe-schedule/agent/#keepalive-monitoring +[6]: https://bonsai.sensu.io/assets/sensu/sensu-servicenow-handler +[7]: ../../observe-process/send-data-sumo-logic/ +[8]: ../../observe-process/send-pagerduty-alerts/ +[9]: ../../observe-schedule/agent/#ephemeral-agent-configuration +[10]: ../../observe-schedule/agent/#agent-deregistration-handler-attribute +[11]: ../../observe-schedule/backend/#deregistration-handler-attribute +[12]: ../../../catalog/sensu-catalog/ +[13]: https://github.com/sensu/catalog/tree/main/integrations/sensu/platform-discovery +[14]: ../../../operations/control-access/create-limited-service-accounts/ diff --git a/content/sensu-go/6.12/observability-pipeline/observe-entities/entities.md b/content/sensu-go/6.12/observability-pipeline/observe-entities/entities.md new file mode 100644 index 0000000000..42ff7acf3f --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-entities/entities.md @@ -0,0 +1,1942 @@ +--- +title: "Entities reference" +linkTitle: "Entities Reference" +reference_title: "Entities" +type: "reference" +description: "Read this reference to learn about Sensu entities, which represent anything that needs to be monitored, including a full range of apps and infrastructure." +weight: 10 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: observe-entities +--- + +An entity represents anything that needs to be monitored, such as a server, container, or network switch, including the full range of infrastructure, runtime, and application types that compose a complete monitoring environment. +Sensu uses [agent entities][31], [proxy entities][32], and [service entities][40]. + +Sensu's free entity limit is 100 entities. +All [commercial features][9] are available for free in the packaged Sensu Go distribution for up to 100 entities. +If your Sensu instance includes more than 100 entities, [contact us][10] to learn how to upgrade your installation and increase your limit. + +Learn more about entity limits in the [license reference][29]. +Read the [announcement on our blog][11] for more information about our usage policy. + +## Create and manage agent entities + +When an agent connects to a backend, the agent entity definition is created from the information in the `agent.yml` configuration file. +The default `agent.yml` file location [depends on your operating system][35]. + +### Agent entity example + +This example shows the resource definition for an agent entity: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Entity +api_version: core/v2 +metadata: + name: webserver01 +spec: + deregister: false + deregistration: {} + entity_class: agent + last_seen: 1542667231 + redact: + - password + - passwd + - pass + - api_key + - api_token + - access_key + - secret_key + - private_key + - secret + subscriptions: + - entity:webserver01 + system: + arch: amd64 + libc_type: glibc + vm_system: kvm + vm_role: host + cloud_provider: null + processes: + - name: Slack + pid: 1349 + ppid: 0 + status: Ss + background: true + running: true + created: 1582137786 + memory_percent: 1.09932518 + cpu_percent: 0.3263987595984941 + - name: Slack Helper + pid: 1360 + ppid: 1349 + status: Ss + background: true + running: true + created: 1582137786 + memory_percent: 0.146866455 + cpu_percent: 0.30897618146109257 + hostname: sensu2-centos + network: + interfaces: + - addresses: + - 127.0.0.1/8 + - ::1/128 + name: lo + - addresses: + - 10.0.2.15/24 + - fe80::26a5:54ec:cf0d:9704/64 + mac: 08:00:27:11:ad:d2 + name: enp0s3 + - addresses: + - 172.28.128.3/24 + - fe80::a00:27ff:febc:be60/64 + mac: 08:00:27:bc:be:60 + name: enp0s8 + os: linux + platform: centos + platform_family: rhel + platform_version: 7.4.1708 + sensu_agent_version: 1.0.0 + user: agent +{{< /code >}} + +{{< code json >}} +{ + "type": "Entity", + "api_version": "core/v2", + "metadata": { + "name": "webserver01" + }, + "spec": { + "entity_class": "agent", + "system": { + "hostname": "sensu2-centos", + "os": "linux", + "platform": "centos", + "platform_family": "rhel", + "platform_version": "7.4.1708", + "network": { + "interfaces": [ + { + "name": "lo", + "addresses": [ + "127.0.0.1/8", + "::1/128" + ] + }, + { + "name": "enp0s3", + "mac": "08:00:27:11:ad:d2", + "addresses": [ + "10.0.2.15/24", + "fe80::26a5:54ec:cf0d:9704/64" + ] + }, + { + "name": "enp0s8", + "mac": "08:00:27:bc:be:60", + "addresses": [ + "172.28.128.3/24", + "fe80::a00:27ff:febc:be60/64" + ] + } + ] + }, + "arch": "amd64", + "libc_type": "glibc", + "vm_system": "kvm", + "vm_role": "host", + "cloud_provider": "", + "processes": [ + { + "name": "Slack", + "pid": 1349, + "ppid": 0, + "status": "Ss", + "background": true, + "running": true, + "created": 1582137786, + "memory_percent": 1.09932518, + "cpu_percent": 0.3263987595984941 + }, + { + "name": "Slack Helper", + "pid": 1360, + "ppid": 1349, + "status": "Ss", + "background": true, + "running": true, + "created": 1582137786, + "memory_percent": 0.146866455, + "cpu_percent": 0.308976181461092553 + } + ] + }, + "sensu_agent_version": "1.0.0", + "subscriptions": [ + "entity:webserver01" + ], + "last_seen": 1542667231, + "deregister": false, + "deregistration": {}, + "user": "agent", + "redact": [ + "password", + "passwd", + "pass", + "api_key", + "api_token", + "access_key", + "secret_key", + "private_key", + "secret" + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +### Manage agent entities via the backend + +You can manage agent entities via the backend with [sensuctl][37], the [core/v2/entities API endpoints][36], and the [web UI][33], just like any other Sensu resource. +This means you do not need to update the `agent.yml` configuration file to add, update, or delete agent entity attributes like subscriptions and labels. + +Management via the backend is the default configuration for agent entities. + +{{% notice note %}} +**NOTE**: If you manage an agent entity via the backend, you cannot modify the agent entity with the `agent.yml` configuration file unless you delete the entity. +In this case, the entity attributes in `agent.yml` are used only for initial entity creation unless you delete the entity. +{{% /notice %}} + +If you delete an agent entity that you modified with sensuctl, the core/v2/entities API endpoints, or the web UI, it will revert to the original configuration from `agent.yml`. +If you change an agent entity's class to `proxy`, the backend will revert the change to `agent`. + +### Manage agent entities via the agent + +If you prefer, you can manage agent entities via the agent rather than the backend. +To do this, add the [`agent-managed-entity`][16] configuration option when you start the Sensu agent or set `agent-managed-entity: true` in your `agent.yml` file. + +When you start an agent with the `agent-managed-entity` configuration option set to `true`, the agent becomes responsible for managing its entity configuration. +An entity managed by this agent will include the label `sensu.io/managed_by: sensu-agent`. +You cannot update these agent-managed entities via the Sensu backend REST API. +To change an agent's configuration, restart the agent. + +You can also maintain agent entities based on `agent.yml` by creating ephemeral agent entities with the [deregister attribute][34] set to `true`. +With this setting, the agent entity will deregister every time the agent process stops and its keepalive expires. +When it restarts, it will revert to the original configuration from `agent.yml` +You must set `deregister: true` in `agent.yml` before the agent entity is created. + +## Create and manage proxy entities + +Proxy entities allow Sensu to monitor external resources on systems where you cannot install a Sensu agent, like a network switch or website. + +You can create proxy entities the same way you would create agent entities, but Sensu can also dynamically create them when an entity does not already exist for a check result and add them to the entity store. +In this case, Sensu will use the [`proxy_entity_name`][45] defined in the check to register proxy entities for your external resources. + +Proxy entity registration differs from keepalive-based registration because the registration event happens while processing a check result instead of a keepalive message. + +Modify proxy entities as needed via the backend with [sensuctl][37], the [core/v2/entities API endpoints][36], and the [web UI][33]. + +{{% notice note %}} +**NOTE**: If you start an agent with the same name as an existing proxy entity, Sensu will change the proxy entity's class to `agent` and update its `system` field with information from the agent configuration. +{{% /notice %}} + +### Proxy entity example + +This example shows the resource definition for a proxy entity: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Entity +api_version: core/v2 +metadata: + name: sensu-docs +spec: + deregister: false + deregistration: {} + entity_class: proxy + last_seen: 0 + sensu_agent_version: 1.0.0 + subscriptions: null + system: + cloud_provider: "" + libc_type: "" + network: + interfaces: null + processes: null + vm_role: "" + vm_system: "" +{{< /code >}} + +{{< code json >}} +{ + "type": "Entity", + "api_version": "core/v2", + "metadata": { + "name": "sensu-docs" + }, + "spec": { + "deregister": false, + "deregistration": { + }, + "entity_class": "proxy", + "last_seen": 0, + "sensu_agent_version": "1.0.0", + "subscriptions": null, + "system": { + "cloud_provider": "", + "libc_type": "", + "network": { + "interfaces": null + }, + "processes": null, + "vm_role": "", + "vm_system": "" + } + } +} +{{< /code >}} + +{{< /language-toggle >}} + +### Checks for proxy entities + +Proxy entities allow Sensu to monitor external resources on systems or devices where a Sensu agent cannot be installed, like a network switch, website, or API endpoint. + +You can configure a [proxy check][46] that includes a [`proxy_entity_name`][45] to associate the check results with a specific proxy entity. +On the first check result, if the named proxy entity does not exist, Sensu will create it. +You can also use proxy checks to monitor multiple proxy entities based on entity attributes specified in the check definition's [`proxy_requests`][47] attribute. + +When you create a proxy check, make sure the check definition includes a subscription that matches the subscription of at least one agent entity to define which agents will run the check. +Proxy entities do not use subscriptions. + +Read [Monitor external resources with proxy entities][17] for details about creating proxy checks for one or more proxy entities. + +### Proxy entities and round robin scheduling + +Proxy entities make [round robin check scheduling][18] more useful because they allow you to combine all round robin events into a single event. +Instead of having a separate event for each agent entity, you have a single event for the entire round robin. + +If you don't use a proxy entity for round robin scheduling, you could have several failures in a row, but each event will only be aware of one of the failures. + +If you use a proxy entity without round robin scheduling, and several agents share the same subscription, they will all execute the check for the proxy entity and you'll get duplicate results. +When you enable round robin, you'll get one agent per interval executing the proxy check, but the event will always be listed under the proxy entity. + +Use [proxy entity filters][19] to establish a many-to-many relationship between agent entities and proxy entities if you want even more power over the grouping. + +## Create and manage service entities + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access business service monitoring (BSM), including service entities, in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} + +{{% notice note %}} +**NOTE**: Business service monitoring (BSM) is in public preview and is subject to change. +{{% /notice %}} + +Service entities are dynamically created entities that Sensu adds to the entity store when a [service component][39] generates an event. +Service entities allow Sensu to monitor [business services][38]. + +Create and modify service entities via the backend with [sensuctl][37], the [core/v2/entities API endpoints][36], and the [web UI][33]. + +### Service entity example + +This example shows the resource definition for a service entity: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Entity +api_version: core/v2 +metadata: + name: postgresql +spec: + entity_class: service +{{< /code >}} + +{{< code json >}} +{ + "type": "Entity", + "api_version": "core/v2", + "metadata": { + "name": "postgresql" + }, + "spec": { + "entity_class": "service" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Backend entities + +When a backend [starts up][41], Sensu automatically creates the [`sensu-system` namespace][44] and a new entity with `entity_class: backend`. +Sensu populates the backend entity with the backend's system information. + +The backend uses its own entity to report cluster state errors. +Backend entities can generate events due to error conditions like unavailable secrets providers or secrets. +Events generated by a sensu-agent running on the backend host are also associated with the backend entity. + +To prevent overloading the event bus with backend events, Sensu generates backend events no more than every 30 seconds, unless the status changes. +Sensu does not generate keepalive events for backend entities. + +### Backend entity example + +Here is an example definition for a backend entity: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Entity +api_version: core/v2 +metadata: + name: 6b6264feda40 + namespace: sensu-system +spec: + deregister: false + deregistration: {} + entity_class: backend + last_seen: 0 + sensu_agent_version: '' + subscriptions: null + system: + arch: amd64 + cloud_provider: '' + hostname: 6b6264feda40 + libc_type: glibc + network: + interfaces: + - addresses: + - 127.0.0.1/8 + name: lo + - addresses: null + name: tunl0 + - addresses: null + name: ip6tnl0 + - addresses: + - 172.18.0.4/16 + mac: 02:42:ac:12:00:04 + name: eth0 + os: linux + platform: redhat + platform_family: rhel + platform_version: '7.9' + processes: null + vm_role: guest + vm_system: '' +{{< /code >}} + +{{< code json >}} +{ + "type": "Entity", + "api_version": "core/v2", + "metadata": { + "name": "6b6264feda40", + "namespace": "sensu-system" + }, + "spec": { + "deregister": false, + "deregistration": { + }, + "entity_class": "backend", + "last_seen": 0, + "sensu_agent_version": "", + "subscriptions": null, + "system": { + "arch": "amd64", + "cloud_provider": "", + "hostname": "6b6264feda40", + "libc_type": "glibc", + "network": { + "interfaces": [ + { + "addresses": [ + "127.0.0.1/8" + ], + "name": "lo" + }, + { + "addresses": null, + "name": "tunl0" + }, + { + "addresses": null, + "name": "ip6tnl0" + }, + { + "addresses": [ + "172.18.0.4/16" + ], + "mac": "02:42:ac:12:00:04", + "name": "eth0" + } + ] + }, + "os": "linux", + "platform": "redhat", + "platform_family": "rhel", + "platform_version": "7.9", + "processes": null, + "vm_role": "guest", + "vm_system": "" + } + } +} +{{< /code >}} + +{{< /language-toggle >}} + +### Access backend entities + +Only cluster admins have access to the `sensu-system` namespace and the backend entities it contains. + +If you have cluster admin permissions, you can use [sensuctl][42] and the [web UI][43] to access backend entities like other entities. + +Cluster admins who have write permissions for the `sensu-system` namespace can edit **only** labels and subscriptions for backend entities. + +### Backend entities and agent information + +Sensu uses the same algorithm to determine backend entity names as the agent uses to determine entity names. + +If a backend and an agent try to create the same entity, the entity class will default to `backend`. +The information provided by the backend takes precedence over the information provided by the agent. +The backend should update backend entities to use information from the backend instead of from the agent. + +### Delete a backend entity + +Cluster admins can manually delete backend entities with [sensuctl][42] or the [web UI][43]. + +## Manage entity labels + +Labels are custom attributes that Sensu includes with observation event data that you can use for response and web UI view searches. +In contrast to annotations, you can use labels to filter [API responses][14], [sensuctl responses][15], and [web UI search views][23]. + +Limit labels to metadata you need to use for response filtering and searches. +For complex, non-identifying metadata that you will *not* need to use in response filtering and searches, use [annotations][20] rather than labels. + +### Agent entity labels {#agent-entities-managed} + +For new entities with class `agent`, you can define entity attributes in the `/etc/sensu/agent.yml` configuration file. +For example, to add a `url` label, open `/etc/sensu/agent.yml` and add configuration for `labels`: + +{{< code yml >}} +labels: + url: sensu.docs.io +{{< /code >}} + +Or, use `sensu-agent start` configuration flags: + +{{< code shell >}} +sensu-agent start --labels url=sensu.docs.io +{{< /code >}} + +{{% notice note %}} +**NOTE**: The entity attributes in `agent.yml` are used only for initial entity creation. +Modify existing agent entities via the backend with [sensuctl](../../../sensuctl/create-manage-resources/#update-resources), the [core/v2/entities API endpoints](../../../api/core/entities/), and the [web UI](../../../web-ui/view-manage-resources/#manage-entities). +{{% /notice %}} + +### Proxy entity labels {#proxy-entities-managed} + +For entities with class `proxy`, you can create and manage labels with sensuctl. + +For example, suppose you have a proxy entity like this one: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Entity +api_version: core/v2 +metadata: + labels: + url: docs.sensu.io + name: sensu-docs +spec: + deregister: false + entity_class: proxy + sensu_agent_version: 1.0.0 +{{< /code >}} + +{{< code json >}} +{ + "type": "Entity", + "api_version": "core/v2", + "metadata": { + "labels": { + "url": "docs.sensu.io" + }, + "name": "sensu-docs" + }, + "spec": { + "deregister": false, + "entity_class": "proxy", + "sensu_agent_version": "1.0.0" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +To add a `proxy_type` label to this existing entity, run the following command to open the entity definition: + +{{< code shell >}} +sensuctl edit entity sensu-docs +{{< /code >}} + +Then, update the metadata scope in the entity definition to add the `proxy_type` label as shown below: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Entity +api_version: core/v2 +metadata: + labels: + url: docs.sensu.io + proxy_type: website + name: sensu-docs +spec: + '...': '...' +{{< /code >}} + +{{< code json >}} +{ + "type": "Entity", + "api_version": "core/v2", + "metadata": { + "labels": { + "url": "docs.sensu.io", + "proxy_type": "website" + }, + "name": "sensu-docs" + }, + "spec": { + "...": "..." + } +} +{{< /code >}} + +{{< /language-toggle >}} + +Save your changes to update the proxy entity definition with the `proxy_type` label. + +### Service entity labels + +For entities with class `service`, you can create and manage labels with sensuctl. +To create a service entity with a `service_type` label using sensuctl `create`, create a file called `service-entity.json` with an entity definition that includes `labels`: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Entity +api_version: core/v2 +metadata: + name: postgresql + labels: + service_type: datastore +spec: + entity_class: service +{{< /code >}} + +{{< code json >}} +{ + "type": "Entity", + "api_version": "core/v2", + "metadata": { + "name": "postgresql", + "labels": { + "service_type": "datastore" + } + }, + "spec": { + "entity_class": "service" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +Then run sensuctl create to create the entity based on the definition: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl create --file service-entity.yml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl create --file service-entity.json +{{< /code >}} + +{{< /language-toggle >}} + +To add a label to an existing service entity, use sensuctl edit. +For example, to add a `region` label to a `postgresql` entity: + +{{< code shell >}} +sensuctl edit entity postgresql +{{< /code >}} + +And update the metadata scope to include the `region` label: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Entity +api_version: core/v2 +metadata: + labels: + service_type: datastore + region: us-west-1 + name: postgresql +spec: + '...': '...' +{{< /code >}} + +{{< code json >}} +{ + "type": "Entity", + "api_version": "core/v2", + "metadata": { + "labels": { + "service_type": "datastore", + "region": "us-west-1" + }, + "name": "postgresql" + }, + "spec": { + "...": "..." + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Entities specification + +### Top-level attributes + +api_version | +-------------|------ +description | Top-level attribute that specifies the Sensu API group and version. For entities in this version of Sensu, this attribute should always be `core/v2`. +required | Required for entity definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][12]. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +api_version: core/v2 +{{< /code >}} +{{< code json >}} +{ + "api_version": "core/v2" +} +{{< /code >}} +{{< /language-toggle >}} + +metadata | +-------------|------ +description | Top-level collection of metadata about the entity, including `name`, `namespace`, and `created_by` as well as custom `labels` and `annotations`. The `metadata` map is always at the top level of the entity definition. This means that in `wrapped-json` and `yaml` formats, the `metadata` scope occurs outside the `spec` scope. Read [metadata attributes][8] for details. +required | Required for entity definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][12]. +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +metadata: + name: webserver01 + namespace: default + created_by: admin + labels: + region: us-west-1 + annotations: + slack-channel: "#monitoring" +{{< /code >}} +{{< code json >}} +{ + "metadata": { + "name": "webserver01", + "namespace": "default", + "created_by": "admin", + "labels": { + "region": "us-west-1" + }, + "annotations": { + "slack-channel": "#monitoring" + } + } +} +{{< /code >}} +{{< /language-toggle >}} + +spec | +-------------|------ +description | Top-level map that includes the entity [spec attributes][13]. +required | Required for entity definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][12]. +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +spec: + entity_class: agent + system: + hostname: sensu2-centos + os: linux + platform: centos + platform_family: rhel + platform_version: 7.4.1708 + network: + interfaces: + - name: lo + addresses: + - 127.0.0.1/8 + - "::1/128" + - name: enp0s3 + mac: '08:00:27:11:ad:d2' + addresses: + - 10.0.2.15/24 + - fe80::26a5:54ec:cf0d:9704/64 + - name: enp0s8 + mac: '08:00:27:bc:be:60' + addresses: + - 172.28.128.3/24 + - fe80::a00:27ff:febc:be60/64 + arch: amd64 + libc_type: glibc + vm_system: kvm + vm_role: host + cloud_provider: '' + processes: + - name: Slack + pid: 1349 + ppid: 0 + status: Ss + background: true + running: true + created: 1582137786 + memory_percent: 1.09932518 + cpu_percent: 0.3263987595984941 + - name: Slack Helper + pid: 1360 + ppid: 1349 + status: Ss + background: true + running: true + created: 1582137786 + memory_percent: 0.146866455 + cpu_percent: 0.30897618146109257 + sensu_agent_version: 1.0.0 + subscriptions: + - entity:webserver01 + last_seen: 1542667231 + deregister: false + deregistration: {} + user: agent + redact: + - password + - passwd + - pass + - api_key + - api_token + - access_key + - secret_key + - private_key + - secret +{{< /code >}} +{{< code json >}} +{ + "spec": { + "entity_class": "agent", + "system": { + "hostname": "sensu2-centos", + "os": "linux", + "platform": "centos", + "platform_family": "rhel", + "platform_version": "7.4.1708", + "network": { + "interfaces": [ + { + "name": "lo", + "addresses": [ + "127.0.0.1/8", + "::1/128" + ] + }, + { + "name": "enp0s3", + "mac": "08:00:27:11:ad:d2", + "addresses": [ + "10.0.2.15/24", + "fe80::26a5:54ec:cf0d:9704/64" + ] + }, + { + "name": "enp0s8", + "mac": "08:00:27:bc:be:60", + "addresses": [ + "172.28.128.3/24", + "fe80::a00:27ff:febc:be60/64" + ] + } + ] + }, + "arch": "amd64", + "libc_type": "glibc", + "vm_system": "kvm", + "vm_role": "host", + "cloud_provider": "", + "processes": [ + { + "name": "Slack", + "pid": 1349, + "ppid": 0, + "status": "Ss", + "background": true, + "running": true, + "created": 1582137786, + "memory_percent": 1.09932518, + "cpu_percent": 0.3263987595984941 + }, + { + "name": "Slack Helper", + "pid": 1360, + "ppid": 1349, + "status": "Ss", + "background": true, + "running": true, + "created": 1582137786, + "memory_percent": 0.146866455, + "cpu_percent": 0.30897618146109257 + } + ] + }, + "sensu_agent_version": "1.0.0", + "subscriptions": [ + "entity:webserver01" + ], + "last_seen": 1542667231, + "deregister": false, + "deregistration": {}, + "user": "agent", + "redact": [ + "password", + "passwd", + "pass", + "api_key", + "api_token", + "access_key", + "secret_key", + "private_key", + "secret" + ] + } +} +{{< /code >}} +{{< /language-toggle >}} + +type | +-------------|------ +description | Top-level attribute that specifies the [`sensuctl create`][12] resource type. Entities should always be type `Entity`. +required | Required for entity definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][12]. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +type: Entity +{{< /code >}} +{{< code json >}} +{ + "type": "Entity" +} +{{< /code >}} +{{< /language-toggle >}} + +### Metadata attributes + + + +| annotations | | +-------------|------ +description | Non-identifying metadata to include with observation event data that you can access with [event filters][6]. You can use annotations to add data that's meaningful to people or external tools that interact with Sensu.

    In contrast to labels, you cannot use annotations in [API response filtering][14], [sensuctl response filtering][15], or [web UI views][30].{{% notice note %}} +**NOTE**: For annotations defined in agent.yml or backend.yml, the keys are automatically modified to use all lower-case letters. For example, if you define the annotation `webhookURL: "https://my-webhook.com"` in agent.yml or backend.yml, it will be listed as `webhookurl: "https://my-webhook.com"` in entity definitions.

    Key cases are **not** modified for annotations you define with a command line flag or an environment variable. +{{% /notice %}} +required | false +type | Map of key-value pairs. Keys and values can be any valid UTF-8 string. +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +annotations: + managed-by: ops + playbook: www.example.url +{{< /code >}} +{{< code json >}} +{ + "annotations": { + "managed-by": "ops", + "playbook": "www.example.url" + } +} +{{< /code >}} +{{< /language-toggle >}} + +| created_by | | +-------------|------ +description | Username of the Sensu user who created the entity or last updated the entity. Sensu automatically populates the `created_by` field when the entity is created or updated. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +created_by: admin +{{< /code >}} +{{< code json >}} +{ + "created_by": "admin" +} +{{< /code >}} +{{< /language-toggle >}} + +| labels | | +-------------|------ +description | Custom attributes to include with observation event data that you can use for response and web UI view filtering.

    If you include labels in your event data, you can filter [API responses][14], [sensuctl responses][15], and [web UI views][23] based on them. In other words, labels allow you to create meaningful groupings for your data.

    Limit labels to metadata you need to use for response filtering. For complex, non-identifying metadata that you will *not* need to use in response filtering, use annotations rather than labels.{{% notice note %}} +**NOTE**: For labels that you define in agent.yml or backend.yml, the keys are automatically modified to use all lower-case letters. For example, if you define the label `proxyType: "website"` in agent.yml or backend.yml, it will be listed as `proxytype: "website"` in entity definitions.

    Key cases are **not** modified for labels you define with a command line flag or an environment variable. +{{% /notice %}} +required | false +type | Map of key-value pairs. Keys can contain only letters, numbers, and underscores and must start with a letter. Values can be any valid UTF-8 string. +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +labels: + environment: development + region: us-west-2 +{{< /code >}} +{{< code json >}} +{ + "labels": { + "environment": "development", + "region": "us-west-2" + } +} +{{< /code >}} +{{< /language-toggle >}} + +| name | | +-------------|------ +description | Unique name of the entity, validated with Go regex [`\A[\w\.\-]+\z`][21]. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +name: example-hostname +{{< /code >}} +{{< code json >}} +{ + "name": "example-hostname" +} +{{< /code >}} +{{< /language-toggle >}} + +| namespace | | +-------------|------ +description | [Sensu RBAC namespace][5] that this entity belongs to. +required | false +type | String +default | `default` +example | {{< language-toggle >}} +{{< code yml >}} +namespace: production +{{< /code >}} +{{< code json >}} +{ + "namespace": "production" +} +{{< /code >}} +{{< /language-toggle >}} + +### Spec attributes + +deregister | +-------------|------ +description | If the entity should be removed when it stops sending keepalive messages, `true`. Otherwise, `false`. +required | false +type | Boolean +default | `false` +example | {{< language-toggle >}} +{{< code yml >}} +deregister: false +{{< /code >}} +{{< code json >}} +{ + "deregister": false +} +{{< /code >}} +{{< /language-toggle >}} + +deregistration | +-------------|------ +description | Map that contains a handler name to use when an agent entity is deregistered. Read [deregistration attributes][2] for more information. +required | false +type | Map +example | {{< language-toggle >}} +{{< code yml >}} +deregistration: + handler: email-handler +{{< /code >}} +{{< code json >}} +{ + "deregistration": { + "handler": "email-handler" + } +}{{< /code >}} +{{< /language-toggle >}} + +entity_class | | +-------------|------ +description | Entity type, validated with Go regex [`\A[\w\.\-]+\z`][21]. Class names have special meaning. An entity that runs an agent is class `agent` and is reserved. Setting the value of `entity_class` to `proxy` creates a proxy entity. An entity that represents a business service is class `service`. For other types of entities, the `entity_class` attribute isn’t required, and you can use it to indicate an arbitrary type of entity (like `lambda` or `switch`). +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +entity_class: agent +{{< /code >}} +{{< code json >}} +{ + "entity_class": "agent" +} +{{< /code >}} +{{< /language-toggle >}} + +last_seen | +-------------|------ +description | Time at which the entity was last seen. In seconds since the Unix epoch. +required | false +type | Integer +example | {{< language-toggle >}} +{{< code yml >}} +last_seen: 1522798317 +{{< /code >}} +{{< code json >}} +{ + "last_seen": 1522798317 +} +{{< /code >}} +{{< /language-toggle >}} + +redact | +-------------|------ +description | List of items to redact from log messages. If a value is provided, it overwrites the default list of items to be redacted. +required | false +type | Array +default | ["password", "passwd", "pass", "api_key", "api_token", "access_key", "secret_key", "private_key", "secret"] +example | {{< language-toggle >}} +{{< code yml >}} +redact: +- extra_secret_tokens +{{< /code >}} +{{< code json >}} +{ + "redact": [ + "extra_secret_tokens" + ] +}{{< /code >}} +{{< /language-toggle >}} + +sensu_agent_version | +---------------------|------ +description | Sensu Semantic Versioning (SemVer) version of the agent entity. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +sensu_agent_version: 1.0.0 +{{< /code >}} +{{< code json >}} +{ + "sensu_agent_version": "1.0.0" +} +{{< /code >}} +{{< /language-toggle >}} + +subscriptions| +-------------|------ +description | List of subscription names for the entity. The entity by default has an entity-specific subscription, in the format of `entity:` where `name` is the entity's hostname. +required | false +type | Array +default | The entity-specific subscription. +example | {{< language-toggle >}} +{{< code yml >}} +subscriptions: +- web +- prod +- entity:example-entity +{{< /code >}} +{{< code json >}} +{ + "subscriptions": [ + "web", + "prod", + "entity:example-entity" + ] +} +{{< /code >}} +{{< /language-toggle >}} + +system | +-------------|------ +description | System information about the entity, such as operating system and platform. Read [system attributes][1] for more information.{{% notice note %}} +**NOTE**: Process discovery is disabled in this version of Sensu. New events will not include data in the `processes` attributes. Instead, the field will be empty: `"processes": null`. +{{% /notice %}} +required | false +type | Map +example | {{< language-toggle >}} +{{< code yml >}} +system: + arch: amd64 + libc_type: glibc + vm_system: kvm + vm_role: host + cloud_provider: null + processes: + - name: Slack + pid: 1349 + ppid: 0 + status: Ss + background: true + running: true + created: 1582137786 + memory_percent: 1.09932518 + cpu_percent: 0.3263987595984941 + - name: Slack Helper + pid: 1360 + ppid: 1349 + status: Ss + background: true + running: true + created: 1582137786 + memory_percent: 0.146866455 + cpu_percent: 0.30897618146109257 + hostname: example-hostname + network: + interfaces: + - addresses: + - 127.0.0.1/8 + - ::1/128 + name: lo + - addresses: + - 93.184.216.34/24 + - 2606:2800:220:1:248:1893:25c8:1946/10 + mac: 52:54:00:20:1b:3c + name: eth0 + os: linux + platform: ubuntu + platform_family: debian + platform_version: "16.04" +{{< /code >}} +{{< code json >}} +{ + "system": { + "hostname": "example-hostname", + "os": "linux", + "platform": "ubuntu", + "platform_family": "debian", + "platform_version": "16.04", + "network": { + "interfaces": [ + { + "name": "lo", + "addresses": [ + "127.0.0.1/8", + "::1/128" + ] + }, + { + "name": "eth0", + "mac": "52:54:00:20:1b:3c", + "addresses": [ + "93.184.216.34/24", + "2606:2800:220:1:248:1893:25c8:1946/10" + ] + } + ] + }, + "arch": "amd64", + "libc_type": "glibc", + "vm_system": "kvm", + "vm_role": "host", + "cloud_provider": "", + "processes": [ + { + "name": "Slack", + "pid": 1349, + "ppid": 0, + "status": "Ss", + "background": true, + "running": true, + "created": 1582137786, + "memory_percent": 1.09932518, + "cpu_percent": 0.3263987595984941 + }, + { + "name": "Slack Helper", + "pid": 1360, + "ppid": 1349, + "status": "Ss", + "background": true, + "running": true, + "created": 1582137786, + "memory_percent": 0.146866455, + "cpu_percent": 0.308976181461092553 + } + ] + } +}{{< /code >}} +{{< /language-toggle >}} + +| user | | +--------------|------ +description | [Sensu RBAC username][22] used by the entity. Agent entities require get, list, create, update, and delete permissions for events across all namespaces. +type | String +default | `agent` +example | {{< language-toggle >}} +{{< code yml >}} +user: agent +{{< /code >}} +{{< code json >}} +{ + "user": "agent" +} +{{< /code >}} +{{< /language-toggle >}} + +### Deregistration attributes + +handler | +-------------|------ +description | Name of the handler to call when an agent entity is deregistered. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +handler: email-handler +{{< /code >}} +{{< code json >}} +{ + "handler": "email-handler" +} +{{< /code >}} +{{< /language-toggle >}} + +### System attributes + +arch | +-------------|------ +description | Entity's system architecture. This value is determined by the Go binary architecture as a function of runtime.GOARCH. An `amd` system running a `386` binary will report the `arch` as `386`. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +arch: amd64 +{{< /code >}} +{{< code json >}} +{ + "arch": "amd64" +} +{{< /code >}} +{{< /language-toggle >}} + +arm_version | +-------------|------ +description | Entity's ARM version. Automatically populated upon agent startup for entities with ARM system architecture. For entities that do not use ARM system architecture, the `arm_version` attribute is omitted from the entity definition. +required | false +type | Integer +example | {{< language-toggle >}} +{{< code yml >}} +arm_version: 7 +{{< /code >}} +{{< code json >}} +{ + "arm_version": 7 +} +{{< /code >}} +{{< /language-toggle >}} + +cloud_provider | +---------------|------ +description | Entity's cloud provider environment. Automatically populated upon agent startup if the [`detect-cloud-provider`][25] configuration option is set. Returned empty unless the agent runs on Amazon Elastic Compute Cloud (EC2), Google Cloud Platform (GCP), or Microsoft Azure. {{% notice note %}} +**NOTE**: This feature can result in several HTTP requests or DNS lookups being performed, so it may not be appropriate for all environments. +{{% /notice %}} +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +"cloud_provider": "" +{{< /code >}} +{{< code json >}} +{ + "cloud_provider": "" +} +{{< /code >}} +{{< /language-toggle >}} + +float_type | +-------------|------ +description | Type of float the entity's system architecture uses: `hardfloat` or `softfloat`. Automatically populated upon agent startup for entities with MIPS, MIPS LE, MIPS 64, or MIPS 64 LE system architecture. For entities that do not use a MIPS system architecture, the `float_type` attribute is omitted from the entity definition. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +float_type: hardfloat +{{< /code >}} +{{< code json >}} +{ + "float_type": "hardfloat" +} +{{< /code >}} +{{< /language-toggle >}} + +hostname | +-------------|------ +description | Hostname of the entity. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +hostname: example-hostname +{{< /code >}} +{{< code json >}} +{ + "hostname": "example-hostname" +} +{{< /code >}} +{{< /language-toggle >}} + +libc_type | +-------------|------ +description | Entity's libc type. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +libc_type: glibc +{{< /code >}} +{{< code json >}} +{ + "libc_type": "glibc" +} +{{< /code >}} +{{< /language-toggle >}} + +network | +-------------|------ +description | Entity's network interface list. Read [network attributes][3] for more information. +required | false +type | Map +example | {{< language-toggle >}} +{{< code yml >}} +network: + interfaces: + - addresses: + - 127.0.0.1/8 + - ::1/128 + name: lo + - addresses: + - 93.184.216.34/24 + - 2606:2800:220:1:248:1893:25c8:1946/10 + mac: 52:54:00:20:1b:3c + name: eth0 +{{< /code >}} +{{< code json >}} +{ + "network": { + "interfaces": [ + { + "name": "lo", + "addresses": [ + "127.0.0.1/8", + "::1/128" + ] + }, + { + "name": "eth0", + "mac": "52:54:00:20:1b:3c", + "addresses": [ + "93.184.216.34/24", + "2606:2800:220:1:248:1893:25c8:1946/10" + ] + } + ] + } +}{{< /code >}} +{{< /language-toggle >}} + +os | +-------------|------ +description | Entity's operating system. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +os: linux +{{< /code >}} +{{< code json >}} +{ + "os": "linux" +} +{{< /code >}} +{{< /language-toggle >}} + +platform | +-------------|------ +description | Entity's operating system distribution. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +platform: ubuntu +{{< /code >}} +{{< code json >}} +{ + "platform": "ubuntu" +} +{{< /code >}} +{{< /language-toggle >}} + +platform_family | +-------------|------ +description | Entity's operating system family. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +platform_family: debian +{{< /code >}} +{{< code json >}} +{ + "platform_family": "debian" +} +{{< /code >}} +{{< /language-toggle >}} + +platform_version | +-------------|------ +description | Entity's operating system version. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +platform_version: 16.04 +{{< /code >}} +{{< code json >}} +{ + "platform_version": "16.04" +} +{{< /code >}} +{{< /language-toggle >}} + +processes | +-------------|------ +description | List of processes on the local agent. Read [processes attributes][26] for more information.{{% notice note %}} +**NOTE**: Process discovery is disabled in this version of Sensu. New events will not include data in the `processes` attributes. Instead, the field will be empty: `"processes": null`. +{{% /notice %}} +required | false +type | Map +example | {{< language-toggle >}} +{{< code yml >}} +processes: +- name: Slack + pid: 1349 + ppid: 0 + status: Ss + background: true + running: true + created: 1582137786 + memory_percent: 1.09932518 + cpu_percent: 0.3263987595984941 +- name: Slack Helper + pid: 1360 + ppid: 1349 + status: Ss + background: true + running: true + created: 1582137786 + memory_percent: 0.146866455 + cpu_percent: 0.30897618146109257 +{{< /code >}} +{{< code json >}} +{ + "processes": [ + { + "name": "Slack", + "pid": 1349, + "ppid": 0, + "status": "Ss", + "background": true, + "running": true, + "created": 1582137786, + "memory_percent": 1.09932518, + "cpu_percent": 0.3263987595984941 + }, + { + "name": "Slack Helper", + "pid": 1360, + "ppid": 1349, + "status": "Ss", + "background": true, + "running": true, + "created": 1582137786, + "memory_percent": 0.146866455, + "cpu_percent": 0.308976181461092553 + } + ] +}{{< /code >}} +{{< /language-toggle >}} + +vm_role | +-------------|------ +description | Entity's virtual machine role. Automatically populated upon agent startup. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +vm_role: host +{{< /code >}} +{{< code json >}} +{ + "vm_role": "host" +} +{{< /code >}} +{{< /language-toggle >}} + +vm_system | +-------------|------ +description | Entity's virtual machine system. Automatically populated upon agent startup. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +vm_system: kvm +{{< /code >}} +{{< code json >}} +{ + "vm_system": "kvm" +} +{{< /code >}} +{{< /language-toggle >}} + +### Network attributes + +interfaces | +-------------|------ +description | List of network interfaces available on the entity, with their associated MAC and IP addresses. Read [interfaces attributes][4] for more information. +required | false +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +interfaces: +- addresses: + - 127.0.0.1/8 + - ::1/128 + name: lo +- addresses: + - 93.184.216.34/24 + - 2606:2800:220:1:248:1893:25c8:1946/10 + mac: 52:54:00:20:1b:3c + name: eth0 +{{< /code >}} +{{< code json >}} +{ + "interfaces": [ + { + "name": "lo", + "addresses": [ + "127.0.0.1/8", + "::1/128" + ] + }, + { + "name": "eth0", + "mac": "52:54:00:20:1b:3c", + "addresses": [ + "93.184.216.34/24", + "2606:2800:220:1:248:1893:25c8:1946/10" + ] + } + ] +}{{< /code >}} +{{< /language-toggle >}} + +### Interfaces attributes + +addresses | +-------------|------ +description | List of IP addresses for the network interface. +required | false +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +addresses: +- 93.184.216.34/24 +- 2606:2800:220:1:248:1893:25c8:1946/10 +{{< /code >}} +{{< code json >}} +{ + "addresses": [ + "93.184.216.34/24", + "2606:2800:220:1:248:1893:25c8:1946/10" + ] +} +{{< /code >}} +{{< /language-toggle >}} + +mac | +-------------|------ +description | Network interface's MAC address. +required | false +type | string +example | {{< language-toggle >}} +{{< code yml >}} +mac: 52:54:00:20:1b:3c +{{< /code >}} +{{< code json >}} +{ + "mac": "52:54:00:20:1b:3c" +} +{{< /code >}} +{{< /language-toggle >}} + +name | +-------------|------ +description | Network interface name. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +name: eth0 +{{< /code >}} +{{< code json >}} +{ + "name": "eth0" +} +{{< /code >}} +{{< /language-toggle >}} + +### Processes attributes + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access processes attributes with the [`discover-processes`](../../observe-schedule/agent/#discover-processes) configuration option in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} + +{{% notice note %}} +**NOTE**: Process discovery is disabled in this version of Sensu. +New events will not include data in the `processes` attributes. +Instead, the field will be empty: `"processes": null`. +{{% /notice %}} + +background | +-------------|------ +description | If `true`, the process is a background process. Otherwise, `false`. +required | false +type | Boolean +example | {{< language-toggle >}} +{{< code yml >}} +background: true +{{< /code >}} +{{< code json >}} +{ + "background": true +} +{{< /code >}} +{{< /language-toggle >}} + +cpu_percent | +-------------|------ +description | Percent of CPU the process is using. The value is returned as a floating-point number where 0.0 = 0% and 1.0 = 100%. For example, the cpu_percent value 0.12639 equals 12.639%. {{% notice note %}} +**NOTE**: The `cpu_percent` attribute is supported on Linux and macOS. +It is not supported on Windows. +{{% /notice %}} +required | false +type | float +example | {{< language-toggle >}} +{{< code yml >}} +cpu_percent: 0.12639 +{{< /code >}} +{{< code json >}} +{ + "cpu_percent": 0.12639 +} +{{< /code >}} +{{< /language-toggle >}} + +created | +-------------|------ +description | Time at which the process was created. In seconds since the Unix epoch. +required | false +type | Integer +example | {{< language-toggle >}} +{{< code yml >}} +created: 1586138786 +{{< /code >}} +{{< code json >}} +{ + "created": 1586138786 +} +{{< /code >}} +{{< /language-toggle >}} + +memory_percent | +-------------|------ +description | Percent of memory the process is using. The value is returned as a floating-point number where 0.0 = 0% and 1.0 = 100%. For example, the memory_percent value 0.19932 equals 19.932%. {{% notice note %}} +**NOTE**: The `memory_percent` attribute is supported on Linux and macOS. +It is not supported on Windows. +{{% /notice %}} +required | false +type | float +example | {{< language-toggle >}} +{{< code yml >}} +memory_percent: 0.19932 +{{< /code >}} +{{< code json >}} +{ + "memory_percent": 0.19932 +} +{{< /code >}} +{{< /language-toggle >}} + +name | +-------------|------ +description | Name of the process. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +name: Slack +{{< /code >}} +{{< code json >}} +{ + "name": "Slack" +} +{{< /code >}} +{{< /language-toggle >}} + +pid | +-------------|------ +description | Process ID of the process. +required | false +type | Integer +example | {{< language-toggle >}} +{{< code yml >}} +pid: 1349 +{{< /code >}} +{{< code json >}} +{ + "pid": 1349 +} +{{< /code >}} +{{< /language-toggle >}} + +ppid | +-------------|------ +description | Parent process ID of the process. +required | false +type | Integer +example | {{< language-toggle >}} +{{< code yml >}} +ppid: 0 +{{< /code >}} +{{< code json >}} +{ + "ppid": 0 +} +{{< /code >}} +{{< /language-toggle >}} + +running | +-------------|------ +description | If `true`, the process is running. Otherwise, `false`. +required | false +type | Boolean +example | {{< language-toggle >}} +{{< code yml >}} +running: true +{{< /code >}} +{{< code json >}} +{ + "running": true +} +{{< /code >}} +{{< /language-toggle >}} + +status | +-------------|------ +description | Status of the process. Read the [Linux `top` manual page][28] for examples. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +status: Ss +{{< /code >}} +{{< code json >}} +{ + "status": "Ss" +} +{{< /code >}} +{{< /language-toggle >}} + + +[1]: #system-attributes +[2]: #deregistration-attributes +[3]: #network-attributes +[4]: #interfaces-attributes +[5]: ../../../operations/control-access/namespaces/ +[6]: ../../observe-filter/filters/ +[7]: ../../observe-schedule/tokens/ +[8]: #metadata-attributes +[9]: ../../../commercial/ +[10]: https://sensu.io/contact +[11]: https://sensu.io/blog/one-year-of-sensu-go +[12]: ../../../sensuctl/create-manage-resources/#create-resources +[13]: #spec-attributes +[14]: ../../../api/#response-filtering +[15]: ../../../sensuctl/filter-responses/ +[16]: ../../observe-schedule/agent/#agent-managed-entity +[17]: ../../observe-entities/monitor-external-resources/ +[18]: ../../observe-schedule/checks/#round-robin-checks +[19]: #proxy-entities-managed +[20]: #annotations-attribute +[21]: https://regex101.com/r/zo9mQU/2 +[22]: ../../../operations/control-access/rbac/#agent-user +[23]: ../../../web-ui/search#search-for-labels +[24]: ../../observe-schedule/checks#proxy-requests-attributes +[25]: ../../observe-schedule/agent/#detect-cloud-provider-option +[26]: #processes-attributes +[28]: https://man7.org/linux/man-pages/man1/top.1.html +[29]: ../../../operations/maintain-sensu/license/#entity-limit +[30]: ../../../web-ui/search/ +[31]: ../#agent-entities +[32]: ../#proxy-entities +[33]: ../../../web-ui/view-manage-resources/#manage-entities +[34]: ../../observe-schedule/agent/#ephemeral-agent-configuration +[35]: ../../observe-schedule/agent/#config-file +[36]: ../../../api/core/entities/ +[37]: ../../../sensuctl/create-manage-resources/#update-resources +[38]: ../../observe-schedule/business-service-monitoring/ +[39]: ../../observe-schedule/service-components/ +[40]: ../#service-entities +[41]: ../../observe-schedule/backend/#startup-and-backend-entities +[42]: ../../../sensuctl/create-manage-resources/ +[43]: ../../../web-ui/view-manage-resources/ +[44]: ../../../operations/control-access/namespaces/#default-namespaces +[45]: ../../observe-schedule/checks/#proxy-entity-name-attribute +[46]: ../../observe-schedule/checks/#proxy-checks +[47]: ../../observe-schedule/checks/#proxy-requests-top-level diff --git a/content/sensu-go/6.12/observability-pipeline/observe-entities/monitor-external-resources.md b/content/sensu-go/6.12/observability-pipeline/observe-entities/monitor-external-resources.md new file mode 100644 index 0000000000..09cae1a7a9 --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-entities/monitor-external-resources.md @@ -0,0 +1,606 @@ +--- +title: "Monitor external resources with proxy entities" +linkTitle: "Monitor External Resources" +guide_title: "Monitor external resources with proxy entities" +type: "guide" +description: "Use Sensu's proxy entities to monitor external resources on systems and devices where you cannot install a Sensu agent, like a network switch or a website." +weight: 30 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: observe-entities +--- + +Proxy entities allow Sensu to monitor external resources on systems and devices where a Sensu agent cannot be installed, like a network switch or a website. +You can create [proxy entities][1] with [sensuctl][8], the [Sensu API][9], and the [`proxy_entity_name` check attribute][2]. +When executing checks that include a `proxy_entity_name` or `proxy_requests` attribute, Sensu agents report the resulting event under the proxy entity instead of the agent entity. + +This guide explains how to use a proxy entity to monitor website status and includes two methods for configuring the required Sensu resources: + +- Follow the [Sensu Catalog integration method][27] to configure the resources you need directly in Sensu web UI. +- Follow the [command line configuration method][28] to manually create the Sensu resources you need. + +This guide also explains how to use [proxy checks to monitor a group of websites][29], with command line configuration instructions. + +## Requirements + +To follow this guide, install the Sensu [backend][19], make sure at least one Sensu [agent][31] is running, and configure [sensuctl][30] to connect to the backend as the [`admin` user][32]. + +## Use a proxy entity to monitor a website (Sensu Catalog configuration) + +Follow the steps in this section to use a Sensu Catalog integration to configure status monitoring for https://sensu.io/. +You'll configure a check with a proxy entity name and Sensu will create an entity to represent https://sensu.io/ and report the status of the site under this entity. + +The Sensu Catalog is part of the Sensu web UI, so you can complete all the necessary configuration directly from your browser. + +### Configure a Sensu entity + +To run the proxy entity check, you'll need a Sensu agent entity with the subscription `run_proxies`. +Here's how to add the subscription: + +1. In the web UI, navigate to the Entities page. + +2. Click the agent entity you want to use to run your check. + +3. At the top right corner of the individual entity's page, click **EDIT** to open the Edit Entity dialog. + +4. Under **Schedule**, type `run_proxies` in the Subscriptions and press **Return**. + +5. Click **SUBMIT** to save your changes. + +On the Entities page and the individual page for the entity, the listed subscriptions should now include `run_proxies`. + +### Create the check with a Sensu Catalog integration + +With your entity subscription configured, you can use the Sensu Catalog to create the check you need to monitor https://sensu.io/. + +1. In the web UI, navigate to the Catalog page. + +2. In the catalog menu on the left, click **Service monitoring** and click the **HTTP Endpoint Monitoring (Remote)** integration. + +3. At the top right corner of the page, click **INSTALL...** to open the HTTP Endpoint Configuration dialog page. + +4. In the HTTP Endpoint Configuration dialog page, update the values in the `HTTP Endpoint Host` and `Interval` fields: + + - HTTP Endpoint Host: type `sensu.io` + - Interval: type `15` + + After you update the values, click **NEXT**. + +5. In the Configure Sensu Subscriptions dialog page, type `run_proxies` in the Subscriptions field and press **Return**. +After you add the subscription, click **NEXT**. + +8. The HTTP Endpoint Monitoring (Remote) integration in the Sensu Catalog includes a dialog page for adding pipelines to filter and handle your check's events. +If you already have a pipeline to use, you can add it now. +Otherwise, click **NEXT** to skip this step. + +9. The Summary dialog page lists definitions for the resources that the integration will add. + + Installing the HTTP Endpoint Monitoring (Remote) integration will add the following resources to your Sensu instance: + + - The `sensu/http-checks` dynamic runtime asset + - Two checks: one to produce endpoint status events and one to collect endpoint metrics + + Click the down-arrow next to any resource to view its complete definition in YAML or JSON format. + +10. Click **APPLY** to save the asset and check definitions for the integration. + +11. Click **FINISH** to return to the integration page. + +### Validate the check + +To make sure that the monitoring check is working properly, confirm that Sensu created an entity to represent sensu.io and the `http-endpoint-healthcheck` check is producing events. + +1. In the web UI, navigate to the Entities page. + +2. Confirm that the Entities page lists a proxy entity named `sensu.io`. + + {{< figure src="/images/go/monitor_external_resources/confirm_proxy_entity_690.png" alt="Confirm the sensu.io proxy entity is listed on the Entities page" link="/images/go/monitor_external_resources/confirm_proxy_entity_690.png" target="_blank" >}} + +3. Click the `sensu.io` entity to open the individual entity page. + +4. Confirm that the individual entity page for `sensu.io` lists an event for the `sensu.io-https-endpoint-healthcheck` check. +Click the event for details and history. + + {{< figure src="/images/go/monitor_external_resources/confirm_event.png" alt="Confirm that the sensu.io-https-endpoint-healthcheck check is producing events" link="/images/go/monitor_external_resources/confirm_event.png" target="_blank" >}} + +## Use a proxy entity to monitor a website (command line configuration) + +In this section, you'll use sensuctl to configure a check with a **proxy entity name** to monitor the status of https://sensu.io/ so that Sensu creates an entity that represents the site and reports the status of the site under this entity. + +### Configure a Sensu entity + +To run the check, you'll need a Sensu agent entity with the subscription `run_proxies`. +Use sensuctl to add the `run_proxies` subscription to the entity the Sensu agent is observing. + +{{% notice note %}} +**NOTE**: To find your entity name, run `sensuctl entity list`. +The `ID` is the name of your entity. +{{% /notice %}} + +Before you run the following code, replace `` with the name of the entity on your system. + +{{< code shell >}} +sensuctl entity update +{{< /code >}} + +- For `Entity Class`, press enter. +- For `Subscriptions`, type `run_proxies` and press enter. + +Before you continue, confirm both Sensu services are running: + +{{< code shell >}} +systemctl status sensu-backend && systemctl status sensu-agent +{{< /code >}} + +The response should indicate `active (running)` for both the Sensu backend and agent. + +### Register dynamic runtime asset + +To power the check for https://sensu.io/ status, you'll use the sensu/http-checks dynamic runtime asset. +This community-tier asset includes the http status command that your check will rely on. + +Use `sensuctl asset add` to register the dynamic runtime asset: + +{{< code shell >}} +sensuctl asset add sensu/http-checks:0.5.0 -r http-checks +{{< /code >}} + +The response will indicate that the asset was added: + +{{< code text >}} +fetching bonsai asset: sensu/http-checks:0.5.0 +added asset: sensu/http-checks:0.5.0 + +You have successfully added the Sensu asset resource, but the asset will not get downloaded until +it's invoked by another Sensu resource (ex. check). To add this runtime asset to the appropriate +resource, populate the "runtime_assets" field with ["http-checks"]. +{{< /code >}} + +This example uses the `-r` (rename) flag to specify a shorter name for the dynamic runtime asset: `http-checks`. + +Use sensuctl to confirm that the dynamic runtime asset is ready to use: + +{{< code shell >}} +sensuctl asset list +{{< /code >}} + +The response should list the sensu/http-checks dynamic runtime asset (renamed to `http-checks`): + +{{< code text >}} + Name URL Hash +────────────── ───────────────────────────────────────────────────────────────────── ────────── + http-checks //assets.bonsai.sensu.io/.../http-checks_0.5.0_windows_amd64.tar.gz 52ae075 + http-checks //assets.bonsai.sensu.io/.../http-checks_0.5.0_darwin_amd64.tar.gz 72d0f15 + http-checks //assets.bonsai.sensu.io/.../http-checks_0.5.0_linux_armv7.tar.gz ef18587 + http-checks //assets.bonsai.sensu.io/.../http-checks_0.5.0_linux_arm64.tar.gz 3504ddf + http-checks //assets.bonsai.sensu.io/.../http-checks_0.5.0_linux_386.tar.gz 60b8883 + http-checks //assets.bonsai.sensu.io/.../http-checks_0.5.0_linux_amd64.tar.gz 1db73a8 +{{< /code >}} + +{{% notice note %}} +**NOTE**: Sensu does not download and install dynamic runtime asset builds onto the system until they are needed for command execution. +{{% /notice %}} + +### Create the check + +Now that the dynamic runtime asset is registered, you can create a check named `check-sensu-site` to run the command `http-check --url https://sensu.io` with the sensu/http-checks dynamic runtime asset, at an interval of 15 seconds, for all agents subscribed to the `run_proxies` subscription, using the `sensu-site` proxy entity name. + +The check includes the `round_robin` attribute set to `true` to distribute the check execution across all agents subscribed to the `run_proxies` subscription and avoid duplicate events. + +To create the `check-sensu-site` check, run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +cat << EOF | sensuctl create +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: check-sensu-site +spec: + command: http-check --url https://sensu.io + interval: 15 + proxy_entity_name: sensu-site + publish: true + round_robin: true + runtime_assets: + - http-checks + subscriptions: + - run_proxies +EOF +{{< /code >}} + +{{< code shell "JSON" >}} +cat << EOF | sensuctl create +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "check-sensu-site" + }, + "spec": { + "command": "http-check --url https://sensu.io", + "interval": 15, + "proxy_entity_name": "sensu-site", + "publish": true, + "round_robin": true, + "runtime_assets": [ + "http-checks" + ], + "subscriptions": [ + "run_proxies" + ] + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + +Use sensuctl to confirm that Sensu added the check: + +{{< code shell >}} +sensuctl check list +{{< /code >}} + +The response should list `check-sensu-site`: + +{{< code text >}} + Name Command Interval Cron Timeout TTL Subscriptions Handlers Assets Hooks Publish? Stdin? Metric Format Metric Handlers +─────────────────── ─────────────────────────────────── ────────── ────── ───────── ───── ─────────────── ────────── ───────────── ─────── ────────── ──────── ─────────────── ────────────────── + check-sensu-site http-check --url https://sensu.io 15 0 0 proxy http-checks true false +{{< /code >}} + +### Validate the check + +Use sensuctl to confirm that Sensu created `sensu-site`. +It might take a few moments for Sensu to execute the check and create the proxy entity. + +{{< code shell >}} +sensuctl entity list +{{< /code >}} + +The response should list the `sensu-site` proxy entity: + +{{< code text >}} + ID Class OS Subscriptions Last Seen +─────────────── ─────── ─────── ─────────────────────────── ──────────────────────────────── + sensu-centos agent linux proxy,entity:sensu-centos 2021-10-21 19:20:04 +0000 UTC + sensu-site proxy entity:sensu-site N/A +{{< /code >}} + +Then, use sensuctl to confirm that Sensu is monitoring `sensu-site` with the `check-sensu-site` check: + +{{< code shell >}} +sensuctl event info sensu-site check-sensu-site +{{< /code >}} + +The response should list `check-sensu-site` status and history data for the `sensu-site` proxy entity: + +{{< code text >}} +=== sensu-site - check-sensu-site +Entity: sensu-site +Check: check-sensu-site +Output: http-check OK: HTTP Status 200 for https://sensu.io +Status: 0 +History: 0 +Silenced: false +Timestamp: 2021-10-21 19:20:06 +0000 UTC +UUID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx +{{< /code >}} + +You can also view the new proxy entity in your Sensu web UI. + +## Use proxy requests to monitor a group of websites (command line configuration) + +Suppose that instead of monitoring just sensu.io, you want to monitor multiple sites, like docs.sensu.io, packagecloud.io, and github.com. +In this section, you'll use sensuctl to configure the `proxy_requests` check attribute, entity labels, and token substitution required to monitor three sites with the same check. + +Before you start, use `sensuctl asset add` to register the sensu/http-checks dynamic runtime asset if you haven't already: + +{{< code shell >}} +sensuctl asset add sensu/http-checks:0.5.0 -r http-checks +{{< /code >}} + +Also, add the `run_proxies` subscription to a Sensu agent entity. +Replace `` with the name of the entity on your system: + +{{< code shell >}} +sensuctl entity update +{{< /code >}} + +- For `Entity Class`, press enter. +- For `Subscriptions`, type `run_proxies` and press enter. + +### Create proxy entities + +Instead of creating a proxy entity using the `proxy_entity_name` check attribute, use sensuctl to create proxy entities to represent the three sites you want to monitor. +Your proxy entities need the `entity_class` attribute set to `proxy` to mark them as proxy entities as well as a few custom `labels` to identify them as a group and pass in individual URLs. + +To add the proxy entity definitions, run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +cat << EOF | sensuctl create +--- +type: Entity +api_version: core/v2 +metadata: + name: sensu-docs + labels: + proxy_type: website + url: https://docs.sensu.io +spec: + entity_class: proxy +--- +type: Entity +api_version: core/v2 +metadata: + name: packagecloud-site + labels: + proxy_type: website + url: https://packagecloud.io +spec: + entity_class: proxy +--- +type: Entity +api_version: core/v2 +metadata: + name: github-site + labels: + proxy_type: website + url: https://github.com +spec: + entity_class: proxy +EOF +{{< /code >}} + +{{< code shell "JSON" >}} +cat << EOF | sensuctl create +{ + "type": "Entity", + "api_version": "core/v2", + "metadata": { + "name": "sensu-docs", + "labels": { + "proxy_type": "website", + "url": "https://docs.sensu.io" + } + }, + "spec": { + "entity_class": "proxy" + } +} +{ + "type": "Entity", + "api_version": "core/v2", + "metadata": { + "name": "packagecloud-site", + "labels": { + "proxy_type": "website", + "url": "https://packagecloud.io" + } + }, + "spec": { + "entity_class": "proxy" + } +} +{ + "type": "Entity", + "api_version": "core/v2", + "metadata": { + "name": "github-site", + "labels": { + "proxy_type": "website", + "url": "https://github.com" + } + }, + "spec": { + "entity_class": "proxy" + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + +{{% notice protip %}} +**PRO TIP**: When you create proxy entities, you can add any custom labels that make sense for your environment. +For example, when monitoring a group of routers, you may want to add `ip_address` labels. +{{% /notice %}} + +Use sensuctl to confirm that the entities were added: + +{{< code shell >}} +sensuctl entity list +{{< /code >}} + +The response should list the new `sensu-docs`, `packagecloud-site`, and `github-site` proxy entities: + +{{< code text >}} + ID Class OS Subscriptions Last Seen +──────────────────── ─────── ─────── ─────────────────────────── ──────────────────────────────── + github-site proxy N/A + packagecloud-site proxy N/A + sensu-centos agent linux proxy,entity:sensu-centos 2021-10-21 19:23:04 +0000 UTC + sensu-docs proxy N/A + sensu-site proxy entity:sensu-site N/A +{{< /code >}} + +### Create a reusable HTTP check + +Now that you have three proxy entities set up, each with a `proxy_type` and `url` label, you can use proxy requests and token substitution to create a single check that monitors all three sites. + +The check includes the `round_robin` attribute set to `true` to distribute the check execution across all agents subscribed to the `run_proxies` subscription and avoid duplicate events. + +To create the following check definition, run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +cat << EOF | sensuctl create +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: check-http +spec: + command: 'http-check --url {{ .labels.url }}' + interval: 15 + proxy_requests: + entity_attributes: + - entity.entity_class == 'proxy' + - entity.labels.proxy_type == 'website' + publish: true + round_robin: true + runtime_assets: + - http-checks + subscriptions: + - run_proxies +EOF +{{< /code >}} + +{{< code shell "JSON" >}} +cat << EOF | sensuctl create +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "check-http" + }, + "spec": { + "command": "http-check --url {{ .labels.url }}", + "interval": 15, + "proxy_requests": { + "entity_attributes": [ + "entity.entity_class == 'proxy'", + "entity.labels.proxy_type == 'website'" + ] + }, + "publish": true, + "runtime_assets": [ + "http-checks" + ], + "round_robin": true, + "subscriptions": [ + "run_proxies" + ] + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + +Your `check-http` check uses the `proxy_requests` attribute to specify the applicable entities. +In this case, you want to run the `check-http` check on all entities of entity class `proxy` and proxy type `website`. +Because you're using this check to monitor multiple sites, the check command uses token substitution to apply the correct `url`. + +Use sensuctl to confirm that Sensu created the check: + +{{< code shell >}} +sensuctl check list +{{< /code >}} + +The response should include the `check-http` check: + +{{< code text >}} + Name Command Interval Cron Timeout TTL Subscriptions Handlers Assets Hooks Publish? Stdin? Metric Format Metric Handlers +─────────────────── ──────────────────────────────────── ────────── ────── ───────── ───── ─────────────── ────────── ───────────── ─────── ────────── ──────── ─────────────── ────────────────── + check-http http-check --url {{ .labels.url }} 15 0 0 proxy http-checks true false + check-sensu-site http-check --url https://sensu.io 15 0 0 proxy http-checks true false +{{< /code >}} + +### Validate the check + +Use sensuctl to confirm that Sensu is monitoring docs.sensu.io, packagecloud.io, and github.com with the `check-http` check, returning a status of `0` (OK): + +{{< code shell >}} +sensuctl event list +{{< /code >}} + +The response should list check status data for the `sensu-docs`, `packagecloud-site`, and `github-site` proxy entities: + +{{< code text >}} + Entity Check Output Status Silenced Timestamp UUID +──────────────────── ────────────────── ──────────────────────────────────────────────────────────────────────── ──────── ────────── ─────────────────────────────── ─────────────────────────────────────── + github-site check-http http-check OK: HTTP Status 200 for https://github.com 0 false 2021-10-21 19:27:04 +0000 UTC xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + + packagecloud-site check-http http-check OK: HTTP Status 200 for https://packagecloud.io 0 false 2021-10-21 19:27:04 +0000 UTC xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + + sensu-centos keepalive Keepalive last sent from sensu-centos at 2021-10-21 19:27:44 +0000 UTC 0 false 2021-10-21 19:27:44 +0000 UTC xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + sensu-docs check-http http-check OK: HTTP Status 200 for https://docs.sensu.io 0 false 2021-10-21 19:27:03 +0000 UTC xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + + sensu-site check-sensu-site http-check OK: HTTP Status 200 for https://sensu.io 0 false 2021-10-21 19:27:05 +0000 UTC xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx +{{< /code >}} + +## What's next + +Now that you know how to run proxy checks to verify website status, you can receive alerts based on the events your checks create. +Configure three more Sensu resources to start receiving alerts: + +- [Event filters][17], which the Sensu backend will apply to the observation data in events. Sensu then sends any events the filters do not remove for processing. +- [Handlers][22], which process the events that filters do not remove. +- [Pipelines][23], which are Sensu resources composed of observation event processing workflows made up of filters, mutators, and handlers. When you list a pipeline in a check definition, all the observability events that the check produces will be processed according to the pipeline’s workflows. + +Follow any of these guides to learn how to configure event filters, handlers, and pipelines and start sending alerts based on event data: + +* [Send email alerts with a pipeline][5] +* [Send PagerDuty alerts with Sensu][6] +* [Send Slack alerts with a pipeline][7] + +You can also send metrics and status data to [Sumo Logic][33]. + +Read more about the Sensu features you used in this guide: + +- [Sensu Catalog][25] +- [Dynamic runtime assets][13] and [sensu/http-checks][16] +- [Proxy checks][3] +- [Round robin checks][18] +- [Token substitution][12] +- [Entity labels][11] +- [sensuctl][8] + +The files you created with check and entity definitions can become part of your [monitoring as code][4] repository. +Storing your Sensu configurations the same way you would store code means they are portable and repeatable. +Monitoring as code makes it possible to move to a more robust deployment without losing what you’ve started here and reproduce one environment’s configuration in another. + + +[1]: ../../observe-entities/#proxy-entities +[2]: ../../observe-schedule/checks/#proxy-entity-name-attribute +[3]: ../../observe-schedule/checks/#proxy-checks +[4]: ../../../operations/monitoring-as-code/ +[5]: ../../observe-process/send-email-alerts/ +[6]: ../../observe-process/send-pagerduty-alerts/ +[7]: ../../observe-process/send-slack-alerts/ +[8]: ../../../sensuctl/ +[9]: ../../../api/core/entities/ +[10]: ../../../web-ui/ +[11]: ../../observe-entities/entities#manage-entity-labels +[12]: ../../observe-schedule/tokens/ +[13]: ../../../plugins/assets/ +[14]: #configure-a-sensu-entity +[15]: #create-the-check +[16]: https://bonsai.sensu.io/assets/sensu/http-checks +[17]: ../../observe-filter/filters/ +[18]: ../../observe-schedule/checks#round-robin-checks +[19]: ../../../operations/deploy-sensu/install-sensu/#install-the-sensu-backend +[20]: ../../observe-schedule/agent#restart-the-service +[21]: ../../../sensuctl/sensuctl-bonsai/#install-dynamic-runtime-asset-definitions +[22]: ../../observe-process/handlers/ +[23]: ../../observe-process/pipelines/ +[24]: https://sensu.io +[25]: ../../../catalog/sensu-catalog/ +[26]: ../../../web-ui/view-manage-resources/#manage-entities +[27]: #use-a-proxy-entity-to-monitor-a-website-sensu-catalog-configuration +[28]: #use-a-proxy-entity-to-monitor-a-website-command-line-configuration +[29]: #use-proxy-requests-to-monitor-a-group-of-websites-command-line-configuration +[30]: ../../../operations/deploy-sensu/install-sensu/#install-sensuctl +[31]: ../../../operations/deploy-sensu/install-sensu/#install-sensu-agents +[32]: ../../../operations/control-access/rbac/#default-users +[33]: ../../observe-process/send-data-sumo-logic/ diff --git a/content/sensu-go/6.12/observability-pipeline/observe-events/_index.md b/content/sensu-go/6.12/observability-pipeline/observe-events/_index.md new file mode 100644 index 0000000000..4e5c9c00cf --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-events/_index.md @@ -0,0 +1,549 @@ +--- +title: "Events" +linkTitle: "Events" +description: "Learn how Sensu uses events to add context to status and metrics check results for comprehensive system and service monitoring and observability." +product: "Sensu Go" +version: "6.12" +weight: 20 +layout: "single" +toc: true +menu: + sensu-go-6.12: + parent: observability-pipeline + identifier: observe-events +--- + + + + +** or click any element in the pipeline to jump to it.** + +Events are generic containers that Sensu uses to provide context to status and metrics check results. +The context, called observation data, is information about the originating entity and the corresponding status or metric check result. + +These generic containers allow Sensu to handle different types of events in the pipeline for comprehensive system and service monitoring and observability. +Events can contain CPU, memory, and disk usage data; custom application metrics; log data you can send to an external database; and more. + +Events require a timestamp, entity, and check. +Each event must contain a check result, whether [status][3] or [metrics][7]. +In certain cases, an event can contain [both][8]. +Because events are polymorphic in nature, it is important to never assume their content (or lack of content). + +Here's an example event that includes both status and metrics data, retrieved with sensuctl event info: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Event +api_version: core/v2 +metadata: + namespace: default +spec: + check: + check_hooks: null + command: http-check --url http://localhost && http-perf --url http://localhost + --warning 1s --critical 2s + duration: 0.022274319 + env_vars: null + executed: 1635959379 + handlers: + - debug + high_flap_threshold: 0 + history: + - executed: 1635952820 + status: 0 + - executed: 1635952835 + status: 0 + - executed: 1635952850 + status: 0 + - executed: 1635952865 + status: 0 + - executed: 1635952880 + status: 0 + interval: 5 + is_silenced: false + issued: 1635952880 + last_ok: 1635952880 + low_flap_threshold: 0 + metadata: + name: collect-metrics + namespace: default + occurrences: 5 + occurrences_watermark: 5 + output: | + http-check OK: HTTP Status 200 for http://localhost + http-perf OK: 0.001150s | dns_duration=0.000257, tls_handshake_duration=0.000000, connect_duration=0.000088, first_byte_duration=0.001131, total_request_duration=0.001150 + output_metric_format: nagios_perfdata + output_metric_handlers: null + pipelines: [] + processed_by: sensu-centos + proxy_entity_name: "" + publish: true + round_robin: false + runtime_assets: + - http-checks + scheduler: memory + secrets: null + state: passing + status: 0 + stdin: false + subdue: null + subscriptions: + - webserver + timeout: 0 + total_state_change: 0 + ttl: 0 + entity: + deregister: false + deregistration: {} + entity_class: agent + last_seen: 1635959379 + metadata: + created_by: admin + name: sensu-centos + namespace: default + redact: + - password + - passwd + - pass + - api_key + - api_token + - access_key + - secret_key + - private_key + - secret + sensu_agent_version: 6.5.4 + subscriptions: + - system + - entity:sensu-centos + - webserver + system: + arch: amd64 + cloud_provider: "" + hostname: sensu-centos + libc_type: glibc + network: + interfaces: + - addresses: + - 127.0.0.1/8 + - ::1/128 + name: lo + - addresses: + - 10.0.2.15/24 + - fe80::20b8:8cea:fa4:2e57/64 + mac: 08:00:27:8b:c9:3f + name: eth0 + - addresses: + - 192.168.200.95/24 + - fe80::a00:27ff:fe40:ab31/64 + mac: 08:00:27:40:ab:31 + name: eth1 + os: linux + platform: centos + platform_family: rhel + platform_version: 7.9.2009 + processes: null + vm_role: guest + vm_system: vbox + user: agent + id: 12545deb-0e0f-480f-addf-34545d5a01c6 + pipelines: null + sequence: 5 + timestamp: 1635952880 +{{< /code >}} + +{{< code json >}} +{ + "type": "Event", + "api_version": "core/v2", + "metadata": { + "namespace": "default" + }, + "spec": { + "check": { + "check_hooks": null, + "command": "http-check --url http://localhost && http-perf --url http://localhost --warning 1s --critical 2s", + "duration": 0.022274319, + "env_vars": null, + "executed": 1635959379, + "handlers": [ + "debug" + ], + "high_flap_threshold": 0, + "history": [ + { + "executed": 1635952820, + "status": 0 + }, + { + "executed": 1635952835, + "status": 0 + }, + { + "executed": 1635952850, + "status": 0 + }, + { + "executed": 1635952865, + "status": 0 + }, + { + "executed": 1635952880, + "status": 0 + } + ], + "interval": 5, + "is_silenced": false, + "issued": 1635952880, + "last_ok": 1635952880, + "low_flap_threshold": 0, + "metadata": { + "name": "collect-metrics", + "namespace": "default" + }, + "occurrences": 5, + "occurrences_watermark": 5, + "output": "http-check OK: HTTP Status 200 for http://localhost\nhttp-perf OK: 0.001150s | dns_duration=0.000257, tls_handshake_duration=0.000000, connect_duration=0.000088, first_byte_duration=0.001131, total_request_duration=0.001150\n", + "output_metric_format": "nagios_perfdata", + "output_metric_handlers": null, + "pipelines": [], + "processed_by": "sensu-centos", + "proxy_entity_name": "", + "publish": true, + "round_robin": false, + "runtime_assets": [ + "http-checks" + ], + "scheduler": "memory", + "secrets": null, + "state": "passing", + "status": 0, + "stdin": false, + "subdue": null, + "subscriptions": [ + "webserver" + ], + "timeout": 0, + "total_state_change": 0, + "ttl": 0 + }, + "entity": { + "deregister": false, + "deregistration": {}, + "entity_class": "agent", + "last_seen": 1635959379, + "metadata": { + "created_by": "admin", + "name": "sensu-centos", + "namespace": "default" + }, + "redact": [ + "password", + "passwd", + "pass", + "api_key", + "api_token", + "access_key", + "secret_key", + "private_key", + "secret" + ], + "sensu_agent_version": "6.5.4", + "subscriptions": [ + "system", + "entity:sensu-centos", + "webserver" + ], + "system": { + "arch": "amd64", + "cloud_provider": "", + "hostname": "sensu-centos", + "libc_type": "glibc", + "network": { + "interfaces": [ + { + "addresses": [ + "127.0.0.1/8", + ":1/128" + ], + "name": "lo" + }, + { + "addresses": [ + "10.0.2.15/24", + "fe80::20b8:8cea:fa4:2e57/64" + ], + "mac": "08:00:27:8b:c9:3f", + "name": "eth0" + }, + { + "addresses": [ + "192.168.200.95/24", + "fe80::a00:27ff:fe40:ab31/64" + ], + "mac": "08:00:27:40:ab:31", + "name": "eth1" + } + ] + }, + "os": "linux", + "platform": "centos", + "platform_family": "rhel", + "platform_version": "7.9.2009", + "processes": null, + "vm_role": "guest", + "vm_system": "vbox" + }, + "user": "agent" + }, + "id": "12545deb-0e0f-480f-addf-34545d5a01c6", + "pipelines": null, + "sequence": 5, + "timestamp": 1635952880 + } +} +{{< /code >}} + +{{< /language-toggle >}} + +{{% notice note %}} +**NOTE**: Metrics data points are not included in events retrieved with sensuctl event info — these events include check output text rather than a set of metrics points. To view metrics points data as shown in the event below, add a [debug handler](../../operations/maintain-sensu/troubleshoot/#use-a-debug-handler) that prints events to a JSON file. +{{% /notice %}} + +{{< code json >}} +{ + "entity": { + "entity_class": "agent", + "system": { + "hostname": "sensu-centos", + "os": "linux", + "platform": "centos", + "platform_family": "rhel", + "platform_version": "7.9.2009", + "network": { + "interfaces": [ + { + "name": "lo", + "addresses": [ + "127.0.0.1/8", + "::1/128" + ] + }, + { + "name": "eth0", + "mac": "08:00:27:8b:c9:3f", + "addresses": [ + "10.0.2.15/24", + "fe80::20b8:8cea:fa4:2e57/64" + ] + }, + { + "name": "eth1", + "mac": "08:00:27:40:ab:31", + "addresses": [ + "192.168.200.95/24", + "fe80::a00:27ff:fe40:ab31/64" + ] + } + ] + }, + "arch": "amd64", + "libc_type": "glibc", + "vm_system": "vbox", + "vm_role": "guest", + "cloud_provider": "", + "processes": null + }, + "subscriptions": [ + "system", + "entity:sensu-centos", + "webserver" + ], + "last_seen": 1635952880, + "deregister": false, + "deregistration": {}, + "user": "agent", + "redact": [ + "password", + "passwd", + "pass", + "api_key", + "api_token", + "access_key", + "secret_key", + "private_key", + "secret" + ], + "metadata": { + "name": "sensu-centos", + "namespace": "default", + "created_by": "admin" + }, + "sensu_agent_version": "6.5.4" + }, + "check": { + "command": "http-check --url http://localhost \\u0026\\u0026 http-perf --url http://localhost --warning 1s --critical 2s", + "handlers": [ + "debug" + ], + "high_flap_threshold": 0, + "interval": 15, + "low_flap_threshold": 0, + "publish": true, + "runtime_assets": [ + "http-checks" + ], + "subscriptions": [ + "webserver" + ], + "proxy_entity_name": "", + "check_hooks": null, + "stdin": false, + "subdue": null, + "ttl": 0, + "timeout": 0, + "round_robin": false, + "duration": 0.018747388, + "executed": 1635952880, + "history": [ + { + "status": 0, + "executed": 1635952820 + }, + { + "status": 0, + "executed": 1635952835 + }, + { + "status": 0, + "executed": 1635952850 + }, + { + "status": 0, + "executed": 1635952865 + }, + { + "status": 0, + "executed": 1635952880 + } + ], + "issued": 1635952880, + "output": "http-check OK: HTTP Status 200 for http://localhost\nhttp-perf OK: 0.001059s | dns_duration=0.000235, tls_handshake_duration=0.000000, connect_duration=0.000083, first_byte_duration=0.001040, total_request_duration=0.001059\n", + "state": "passing", + "status": 0, + "total_state_change": 0, + "last_ok": 1635952880, + "occurrences": 5, + "occurrences_watermark": 5, + "output_metric_format": "nagios_perfdata", + "output_metric_handlers": null, + "env_vars": null, + "metadata": { + "name": "collect-metrics", + "namespace": "default" + }, + "secrets": null, + "is_silenced": false, + "scheduler": "memory", + "processed_by": "sensu-centos", + "pipelines": [] + }, + "metrics": { + "handlers": null, + "points": [ + { + "name": "dns_duration", + "value": 0.000235, + "timestamp": 1635952880, + "tags": null + }, + { + "name": "tls_handshake_duration", + "value": 0, + "timestamp": 1635952880, + "tags": null + }, + { + "name": "connect_duration", + "value": 0.000083, + "timestamp": 1635952880, + "tags": null + }, + { + "name": "first_byte_duration", + "value": 0.00104, + "timestamp": 1635952880, + "tags": null + }, + { + "name": "total_request_duration", + "value": 0.001059, + "timestamp": 1635952880, + "tags": null + } + ] + }, + "metadata": { + "namespace": "default" + }, + "id": "7cde3e3f-beee-408f-b89a-1edccd0d3edb", + "sequence": 5, + "pipelines": null, + "timestamp": 1635952880 +} +{{< /code >}} + +## Checks + +Checks work with the Sensu [agent][11] to produce events automatically. You can use checks to monitor server resources, services, and application health as well as collect and analyze metrics. +Checks define how Sensu will process events, as well as when and where events are generated via [subscriptions and scheduling][12]. + +Read [Monitor server resources][1] to learn more about using checks to generate events. + +## Status-only events + +A Sensu event is created every time a check result is processed by the Sensu server, regardless of the status the result indicates. +The agent creates an event upon receipt of the check execution result and executes any configured [hooks][4] the check might have. +From there, the status result is forwarded to the Sensu backend, where it is filtered, transformed, and processed. +Potentially noteworthy events may be processed by one or more event handlers, for example to send an email or invoke an automated action. + +## Metrics-only events + +Sensu events can be created when the agent receives metrics through the [StatsD listener][5]. +The agent will translate the StatsD metrics to Sensu metric format and place them inside an event. +Because these events do not contain checks, they bypass the store and are sent to the event pipeline and corresponding event handlers. + +## Status and metrics events + +Events that contain _both_ a check and metrics most likely originated from [check output metric extraction][6]. +If a check is configured for metric extraction, the agent will parse the check output and transform it to Sensu metric format. +Both the check results and resulting (extracted) metrics are stored inside the event. +Event handlers from `event.Check.Handlers` and `event.Metrics.Handlers` will be invoked. + +## Proxy entities and events + +You can create events with proxy entities, which are dynamically created entities that Sensu adds to the entity store if an entity does not already exist for a check result. +Proxy entities allow Sensu to monitor external resources on systems where you cannot install a Sensu agent, like a network switch or website. +Read [Monitor external resources][1] to learn how to use a proxy entity to monitor a website. + +## core/v2/events API endpoints + +Sensu's [core/v2/events API endpoints][15] provide HTTP access to create, retrieve, update, and delete events. +If you create a new event that references an entity that does not already exist, the Sensu [backend][16] will automatically create a proxy entity when the event is published. + + +[1]: ../observe-entities/monitor-external-resources/ +[2]: https://bonsai.sensu.io +[3]: #status-only-events +[4]: ../observe-schedule/hooks/ +[5]: ../observe-process/aggregate-metrics-statsd/ +[6]: ../observe-schedule/collect-metrics-with-checks/ +[7]: #metrics-only-events +[8]: #status-and-metrics-events +[11]: ../observe-schedule/agent/ +[12]: ../observe-schedule/ +[13]: #corev2events-api-endpoints +[14]: ../observe-schedule/agent/#detect-silent-failures +[15]: ../../api/core/events/ +[16]: ../observe-schedule/agent/ diff --git a/content/sensu-go/6.12/observability-pipeline/observe-events/events.md b/content/sensu-go/6.12/observability-pipeline/observe-events/events.md new file mode 100644 index 0000000000..0c63af98cd --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-events/events.md @@ -0,0 +1,3376 @@ +--- +title: "Events reference" +linkTitle: "Events Reference" +reference_title: "Events" +type: "reference" +description: "Use Sensu events, containers that provide context for check results, to represent the state of your infrastructure and create automated monitoring workflows." +weight: 20 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: observe-events +--- + +An event is a generic container used by Sensu to provide context to checks and metrics. +The context, called observation data or event data, contains information about the originating entity and the corresponding check or metric result. +An event must contain a [status][4] or [metrics][5]. +In certain cases, an event can contain [both a status and metrics][19]. +These generic containers allow Sensu to handle different types of events in the observability pipeline. +Because events are polymorphic in nature, it is important to never assume their contents (or lack of content). + +## Event format + +Sensu events contain: + +- `entity` scope (required) + - Information about the source of the event, including any attributes defined in the [entity specification][2] +- `check` scope (optional if the `metrics` scope is present) + - Information about how the event was created, including any attributes defined in the [check specification][20] + - Information about the event and its history, including any check attributes defined in the [event specification on this page][21] +- `metrics` scope (optional if the `check` scope is present) + - Metric points in [Sensu metric format][22] +- `timestamp` + - Time that the event occurred in seconds since the Unix epoch +- `id` + - Universally unique identifier (UUID) for the event (logged as `event_id`) + +## Example status-only event + +The following example shows the complete resource definition for a [status-only event][4]: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Event +api_version: core/v2 +metadata: + namespace: default +spec: + check: + check_hooks: null + command: check-cpu-usage -w 75 -c 90 + duration: 5.058211427 + env_vars: null + executed: 1617050501 + handlers: [] + high_flap_threshold: 0 + history: + - executed: 1617050261 + status: 0 + - executed: 1617050321 + status: 0 + - executed: 1617050381 + status: 0 + - executed: 1617050441 + status: 0 + - executed: 1617050501 + status: 0 + interval: 60 + is_silenced: false + processed_by: sensu-centos + issued: 1617050501 + last_ok: 1617050501 + low_flap_threshold: 0 + metadata: + name: check_cpu + namespace: default + occurrences: 5 + occurrences_watermark: 5 + output: | + CheckCPU TOTAL OK: total=0.41 user=0.2 nice=0.0 system=0.2 idle=99.59 iowait=0.0 irq=0.0 softirq=0.0 steal=0.0 guest=0.0 guest_nice=0.0 + output_metric_format: "" + output_metric_handlers: null + proxy_entity_name: "" + publish: true + round_robin: false + runtime_assets: + - check-cpu-usage + scheduler: memory + secrets: null + state: passing + status: 0 + stdin: false + subdue: null + subscriptions: + - system + timeout: 0 + total_state_change: 0 + ttl: 0 + entity: + deregister: false + deregistration: {} + entity_class: agent + last_seen: 1617050501 + metadata: + name: sensu-centos + namespace: default + redact: + - password + - passwd + - pass + - api_key + - api_token + - access_key + - secret_key + - private_key + - secret + sensu_agent_version: 6.2.6 + subscriptions: + - linux + - entity:sensu-centos + system: + arch: amd64 + cloud_provider: "" + hostname: sensu-centos + libc_type: glibc + network: + interfaces: + - addresses: + - 127.0.0.1/8 + - ::1/128 + name: lo + - addresses: + - 10.0.2.15/24 + - fe80::a268:dcce:3be:1c73/64 + mac: 08:00:27:8b:c9:3f + name: eth0 + - addresses: + - 172.28.128.45/24 + - fe80::a00:27ff:feb2:dc46/64 + mac: 08:00:27:b2:dc:46 + name: eth1 + os: linux + platform: centos + platform_family: rhel + platform_version: 7.5.1804 + processes: null + vm_role: guest + vm_system: vbox + user: agent + pipelines: + - api_version: core/v2 + type: Pipeline + name: incident_alerts + id: 3c3e68f6-6db7-40d3-9b84-4d61817ae559 + sequence: 5 + timestamp: 1617050507 +{{< /code >}} + +{{< code json >}} +{ + "type": "Event", + "api_version": "core/v2", + "metadata": { + "namespace": "default" + }, + "spec": { + "check": { + "check_hooks": null, + "command": "check-cpu-usage -w 75 -c 90", + "duration": 5.058211427, + "env_vars": null, + "executed": 1617050501, + "handlers": [], + "high_flap_threshold": 0, + "history": [ + { + "executed": 1617050261, + "status": 0 + }, + { + "executed": 1617050321, + "status": 0 + }, + { + "executed": 1617050381, + "status": 0 + }, + { + "executed": 1617050441, + "status": 0 + }, + { + "executed": 1617050501, + "status": 0 + } + ], + "interval": 60, + "is_silenced": false, + "processed_by": "sensu-centos", + "issued": 1617050501, + "last_ok": 1617050501, + "low_flap_threshold": 0, + "metadata": { + "name": "check_cpu", + "namespace": "default" + }, + "occurrences": 5, + "occurrences_watermark": 5, + "output": "CheckCPU TOTAL OK: total=0.41 user=0.2 nice=0.0 system=0.2 idle=99.59 iowait=0.0 irq=0.0 softirq=0.0 steal=0.0 guest=0.0 guest_nice=0.0\n", + "output_metric_format": "", + "output_metric_handlers": null, + "proxy_entity_name": "", + "publish": true, + "round_robin": false, + "runtime_assets": [ + "check-cpu-usage" + ], + "scheduler": "memory", + "secrets": null, + "state": "passing", + "status": 0, + "stdin": false, + "subdue": null, + "subscriptions": [ + "system" + ], + "timeout": 0, + "total_state_change": 0, + "ttl": 0 + }, + "entity": { + "deregister": false, + "deregistration": {}, + "entity_class": "agent", + "last_seen": 1617050501, + "metadata": { + "name": "sensu-centos", + "namespace": "default" + }, + "redact": [ + "password", + "passwd", + "pass", + "api_key", + "api_token", + "access_key", + "secret_key", + "private_key", + "secret" + ], + "sensu_agent_version": "6.2.6", + "subscriptions": [ + "linux", + "entity:sensu-centos" + ], + "system": { + "arch": "amd64", + "cloud_provider": "", + "hostname": "sensu-centos", + "libc_type": "glibc", + "network": { + "interfaces": [ + { + "addresses": [ + "127.0.0.1/8", + ":1/128" + ], + "name": "lo" + }, + { + "addresses": [ + "10.0.2.15/24", + "fe80::a268:dcce:3be:1c73/64" + ], + "mac": "08:00:27:8b:c9:3f", + "name": "eth0" + }, + { + "addresses": [ + "172.28.128.45/24", + "fe80::a00:27ff:feb2:dc46/64" + ], + "mac": "08:00:27:b2:dc:46", + "name": "eth1" + } + ] + }, + "os": "linux", + "platform": "centos", + "platform_family": "rhel", + "platform_version": "7.5.1804", + "processes": null, + "vm_role": "guest", + "vm_system": "vbox" + }, + "user": "agent" + }, + "pipelines": [ + { + "api_version": "core/v2", + "type": "Pipeline", + "name": "incident_alerts" + } + ], + "id": "3c3e68f6-6db7-40d3-9b84-4d61817ae559", + "sequence": 5, + "timestamp": 1617050507 + } +} +{{< /code >}} + +{{< /language-toggle >}} + +### Example status-only event from the Sensu API + +Sensu sends events to the backend in `json` format, without the outer-level `spec` wrapper or `type` and `api_version` attributes that are included in the `wrapped-json` format. +This is the format that events are in when Sensu sends them to the observability pipeline for processing: + +{{< code json >}} +{ + "check": { + "command": "check-cpu-usage -w 75 -c 90", + "handlers": [], + "high_flap_threshold": 0, + "interval": 60, + "low_flap_threshold": 0, + "publish": true, + "runtime_assets": [ + "check-cpu-usage" + ], + "subscriptions": [ + "system" + ], + "proxy_entity_name": "", + "check_hooks": null, + "stdin": false, + "subdue": null, + "ttl": 0, + "timeout": 0, + "round_robin": false, + "duration": 5.058211427, + "executed": 1617050501, + "history": [ + { + "status": 0, + "executed": 1617050261 + }, + { + "status": 0, + "executed": 1617050321 + }, + { + "status": 0, + "executed": 1617050381 + }, + { + "status": 0, + "executed": 1617050441 + }, + { + "status": 0, + "executed": 1617050501 + } + ], + "issued": 1617050501, + "output": "CheckCPU TOTAL OK: total=0.4 user=0.2 nice=0.0 system=0.2 idle=99.6 iowait=0.0 irq=0.0 softirq=0.0 steal=0.0 guest=0.0 guest_nice=0.0\n", + "state": "passing", + "status": 0, + "total_state_change": 0, + "last_ok": 1617050501, + "occurrences": 5, + "occurrences_watermark": 5, + "output_metric_format": "", + "output_metric_handlers": null, + "env_vars": null, + "metadata": { + "name": "check_cpu", + "namespace": "default" + }, + "secrets": null, + "is_silenced": false, + "processed_by": "sensu-centos", + "scheduler": "memory" + }, + "entity": { + "entity_class": "agent", + "system": { + "hostname": "sensu-centos", + "os": "linux", + "platform": "centos", + "platform_family": "rhel", + "platform_version": "7.5.1804", + "network": { + "interfaces": [ + { + "name": "lo", + "addresses": [ + "127.0.0.1/8", + "::1/128" + ] + }, + { + "name": "eth0", + "mac": "08:00:27:8b:c9:3f", + "addresses": [ + "10.0.2.15/24", + "fe80::a268:dcce:3be:1c73/64" + ] + }, + { + "name": "eth1", + "mac": "08:00:27:b2:dc:46", + "addresses": [ + "172.28.128.45/24", + "fe80::a00:27ff:feb2:dc46/64" + ] + } + ] + }, + "arch": "amd64", + "libc_type": "glibc", + "vm_system": "vbox", + "vm_role": "guest", + "cloud_provider": "", + "processes": null + }, + "subscriptions": [ + "linux", + "entity:sensu-centos" + ], + "last_seen": 1617049781, + "deregister": false, + "deregistration": {}, + "user": "agent", + "redact": [ + "password", + "passwd", + "pass", + "api_key", + "api_token", + "access_key", + "secret_key", + "private_key", + "secret" + ], + "metadata": { + "name": "sensu-centos", + "namespace": "default" + }, + "sensu_agent_version": "6.2.6" + }, + "pipelines": [ + { + "api_version": "core/v2", + "type": "Pipeline", + "name": "incident_alerts" + } + ], + "id": "3c3e68f6-6db7-40d3-9b84-4d61817ae559", + "metadata": { + "namespace": "default" + }, + "sequence": 5, + "timestamp": 1617050507 +} +{{< /code >}} + +## Example metrics-only event + +This example shows a complete [metrics-only event][5], retrieved with sensuctl event info: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Event +api_version: core/v2 +metadata: + namespace: default +spec: + check: + check_hooks: null + command: system-check + duration: 3.012411959 + env_vars: null + executed: 1635959903 + handlers: [] + high_flap_threshold: 0 + history: + - executed: 1635959873 + status: 0 + - executed: 1635959883 + status: 0 + - executed: 1635959893 + status: 0 + - executed: 1635959903 + status: 0 + interval: 10 + is_silenced: false + issued: 1635959903 + last_ok: 1635959903 + low_flap_threshold: 0 + metadata: + labels: + sensu.io/managed_by: sensuctl + name: system-check + namespace: default + occurrences: 4 + occurrences_watermark: 4 + output: |+ + # HELP system_cpu_cores [GAUGE] Number of cpu cores on the system + # TYPE system_cpu_cores GAUGE + system_cpu_cores{} 1 1635959903645 + # HELP system_cpu_idle [GAUGE] Percent of time all cpus were idle + # TYPE system_cpu_idle GAUGE + system_cpu_idle{cpu="cpu0"} 98.94366197187135 1635959903645 + system_cpu_idle{cpu="cpu-total"} 98.94366197187135 1635959903645 + # HELP system_cpu_used [GAUGE] Percent of time all cpus were used + # TYPE system_cpu_used GAUGE + system_cpu_used{cpu="cpu0"} 1.0563380281286499 1635959903645 + system_cpu_used{cpu="cpu-total"} 1.0563380281286499 1635959903645 + # HELP system_cpu_user [GAUGE] Percent of time total cpu was used by normal processes in user mode + # TYPE system_cpu_user GAUGE + system_cpu_user{cpu="cpu0"} 0.7042253521124505 1635959903645 + system_cpu_user{cpu="cpu-total"} 0.7042253521124505 1635959903645 + # HELP system_cpu_system [GAUGE] Percent of time all cpus used by processes executed in kernel mode + # TYPE system_cpu_system GAUGE + system_cpu_system{cpu="cpu0"} 0.35211267605672564 1635959903645 + system_cpu_system{cpu="cpu-total"} 0.35211267605672564 1635959903645 + # HELP system_cpu_nice [GAUGE] Percent of time all cpus used by niced processes in user mode + # TYPE system_cpu_nice GAUGE + system_cpu_nice{cpu="cpu0"} 0 1635959903645 + system_cpu_nice{cpu="cpu-total"} 0 1635959903645 + # HELP system_cpu_iowait [GAUGE] Percent of time all cpus waiting for I/O to complete + # TYPE system_cpu_iowait GAUGE + system_cpu_iowait{cpu="cpu0"} 0 1635959903645 + system_cpu_iowait{cpu="cpu-total"} 0 1635959903645 + # HELP system_cpu_irq [GAUGE] Percent of time all cpus servicing interrupts + # TYPE system_cpu_irq GAUGE + system_cpu_irq{cpu="cpu0"} 0 1635959903645 + system_cpu_irq{cpu="cpu-total"} 0 1635959903645 + # HELP system_cpu_sortirq [GAUGE] Percent of time all cpus servicing software interrupts + # TYPE system_cpu_sortirq GAUGE + system_cpu_sortirq{cpu="cpu0"} 0 1635959903645 + system_cpu_sortirq{cpu="cpu-total"} 0 1635959903645 + # HELP system_cpu_stolen [GAUGE] Percent of time all cpus serviced virtual hosts operating systems + # TYPE system_cpu_stolen GAUGE + system_cpu_stolen{cpu="cpu0"} 0 1635959903645 + system_cpu_stolen{cpu="cpu-total"} 0 1635959903645 + # HELP system_cpu_guest [GAUGE] Percent of time all cpus serviced guest operating system + # TYPE system_cpu_guest GAUGE + system_cpu_guest{cpu="cpu0"} 0 1635959903645 + system_cpu_guest{cpu="cpu-total"} 0 1635959903645 + # HELP system_cpu_guest_nice [GAUGE] Percent of time all cpus serviced niced guest operating system + # TYPE system_cpu_guest_nice GAUGE + system_cpu_guest_nice{cpu="cpu0"} 0 1635959903645 + system_cpu_guest_nice{cpu="cpu-total"} 0 1635959903645 + # HELP system_mem_used [GAUGE] Percent of memory used + # TYPE system_mem_used GAUGE + system_mem_used{} 24.63435866529588 1635959903645 + # HELP system_mem_used_bytes [GAUGE] Used memory in bytes + # TYPE system_mem_used_bytes GAUGE + system_mem_used_bytes{} 2.56159744e+08 1635959903645 + # HELP system_mem_total_bytes [GAUGE] Total memory in bytes + # TYPE system_mem_total_bytes GAUGE + system_mem_total_bytes{} 1.039847424e+09 1635959903645 + # HELP system_swap_used [GAUGE] Percent of swap used + # TYPE system_swap_used GAUGE + system_swap_used{} 0.0976564362648702 1635959903645 + # HELP system_swap_used_bytes [GAUGE] Used swap in bytes + # TYPE system_swap_used_bytes GAUGE + system_swap_used_bytes{} 2.56159744e+08 1635959903645 + # HELP system_swap_total_bytes [GAUGE] Total swap in bytes + # TYPE system_swap_total_bytes GAUGE + system_swap_total_bytes{} 2.147479552e+09 1635959903645 + # HELP system_load_load1 [GAUGE] System load averaged over 1 minute, high load value dependant on number of cpus in system + # TYPE system_load_load1 GAUGE + system_load_load1{} 0.09 1635959903645 + # HELP system_load_load5 [GAUGE] System load averaged over 5 minute, high load value dependent on number of cpus in system + # TYPE system_load_load5 GAUGE + system_load_load5{} 0.04 1635959903645 + # HELP system_load_load15 [GAUGE] System load averaged over 15 minute, high load value dependent on number of cpus in system + # TYPE system_load_load15 GAUGE + system_load_load15{} 0.05 1635959903645 + # HELP system_load_load1_per_cpu [GAUGE] System load averaged over 1 minute normalized by cpu count, values > 1 means system may be overloaded + # TYPE system_load_load1_per_cpu GAUGE + system_load_load1_per_cpu{} 0.09 1635959903645 + # HELP system_load_load5_per_cpu [GAUGE] System load averaged over 5 minute normalized by cpu count, values > 1 means system may be overloaded + # TYPE system_load_load5_per_cpu GAUGE + system_load_load5_per_cpu{} 0.04 1635959903645 + # HELP system_load_load15_per_cpu [GAUGE] System load averaged over 15 minute normalized by cpu count, values > 1 means system may be overloaded + # TYPE system_load_load15_per_cpu GAUGE + system_load_load15_per_cpu{} 0.05 1635959903645 + # HELP system_host_uptime [COUNTER] Host uptime in seconds + # TYPE system_host_uptime COUNTER + system_host_uptime{} 15488 1635959903645 + # HELP system_host_processes [GAUGE] Number of host processes + # TYPE system_host_processes GAUGE + system_host_processes{} 112 1635959903645 + output_metric_format: prometheus_text + output_metric_handlers: null + pipelines: [] + processed_by: sensu-centos + proxy_entity_name: "" + publish: true + round_robin: false + runtime_assets: + - system-check + scheduler: memory + secrets: null + state: passing + status: 0 + stdin: false + subdue: null + subscriptions: + - system + timeout: 0 + total_state_change: 0 + ttl: 0 + entity: + deregister: false + deregistration: {} + entity_class: agent + last_seen: 1635959903 + metadata: + created_by: admin + name: sensu-centos + namespace: default + redact: + - password + - passwd + - pass + - api_key + - api_token + - access_key + - secret_key + - private_key + - secret + sensu_agent_version: 6.5.4 + subscriptions: + - system + - entity:sensu-centos + - webserver + system: + arch: amd64 + cloud_provider: "" + hostname: sensu-centos + libc_type: glibc + network: + interfaces: + - addresses: + - 127.0.0.1/8 + - ::1/128 + name: lo + - addresses: + - 10.0.2.15/24 + - fe80::20b8:8cea:fa4:2e57/64 + mac: 08:00:27:8b:c9:3f + name: eth0 + - addresses: + - 192.168.200.95/24 + - fe80::a00:27ff:fe40:ab31/64 + mac: 08:00:27:40:ab:31 + name: eth1 + os: linux + platform: centos + platform_family: rhel + platform_version: 7.9.2009 + processes: null + vm_role: guest + vm_system: vbox + user: agent + id: 07425e48-e163-47d3-8bc8-17fbaa27e469 + pipelines: null + sequence: 122 + timestamp: 1635959906 +{{< /code >}} + +{{< code json >}} +{ + "type": "Event", + "api_version": "core/v2", + "metadata": { + "namespace": "default" + }, + "spec": { + "check": { + "check_hooks": null, + "command": "system-check", + "duration": 3.012411959, + "env_vars": null, + "executed": 1635959903, + "handlers": [], + "high_flap_threshold": 0, + "history": [ + { + "executed": 1635959873, + "status": 0 + }, + { + "executed": 1635959883, + "status": 0 + }, + { + "executed": 1635959893, + "status": 0 + }, + { + "executed": 1635959903, + "status": 0 + } + ], + "interval": 10, + "is_silenced": false, + "issued": 1635959903, + "last_ok": 1635959903, + "low_flap_threshold": 0, + "metadata": { + "labels": { + "sensu.io/managed_by": "sensuctl" + }, + "name": "system-check", + "namespace": "default" + }, + "occurrences": 4, + "occurrences_watermark": 4, + "output": "# HELP system_cpu_cores [GAUGE] Number of cpu cores on the system\n# TYPE system_cpu_cores GAUGE\nsystem_cpu_cores{} 1 1635959903645\n# HELP system_cpu_idle [GAUGE] Percent of time all cpus were idle\n# TYPE system_cpu_idle GAUGE\nsystem_cpu_idle{cpu=\"cpu0\"} 98.94366197187135 1635959903645\nsystem_cpu_idle{cpu=\"cpu-total\"} 98.94366197187135 1635959903645\n# HELP system_cpu_used [GAUGE] Percent of time all cpus were used\n# TYPE system_cpu_used GAUGE\nsystem_cpu_used{cpu=\"cpu0\"} 1.0563380281286499 1635959903645\nsystem_cpu_used{cpu=\"cpu-total\"} 1.0563380281286499 1635959903645\n# HELP system_cpu_user [GAUGE] Percent of time total cpu was used by normal processes in user mode\n# TYPE system_cpu_user GAUGE\nsystem_cpu_user{cpu=\"cpu0\"} 0.7042253521124505 1635959903645\nsystem_cpu_user{cpu=\"cpu-total\"} 0.7042253521124505 1635959903645\n# HELP system_cpu_system [GAUGE] Percent of time all cpus used by processes executed in kernel mode\n# TYPE system_cpu_system GAUGE\nsystem_cpu_system{cpu=\"cpu0\"} 0.35211267605672564 1635959903645\nsystem_cpu_system{cpu=\"cpu-total\"} 0.35211267605672564 1635959903645\n# HELP system_cpu_nice [GAUGE] Percent of time all cpus used by niced processes in user mode\n# TYPE system_cpu_nice GAUGE\nsystem_cpu_nice{cpu=\"cpu0\"} 0 1635959903645\nsystem_cpu_nice{cpu=\"cpu-total\"} 0 1635959903645\n# HELP system_cpu_iowait [GAUGE] Percent of time all cpus waiting for I/O to complete\n# TYPE system_cpu_iowait GAUGE\nsystem_cpu_iowait{cpu=\"cpu0\"} 0 1635959903645\nsystem_cpu_iowait{cpu=\"cpu-total\"} 0 1635959903645\n# HELP system_cpu_irq [GAUGE] Percent of time all cpus servicing interrupts\n# TYPE system_cpu_irq GAUGE\nsystem_cpu_irq{cpu=\"cpu0\"} 0 1635959903645\nsystem_cpu_irq{cpu=\"cpu-total\"} 0 1635959903645\n# HELP system_cpu_sortirq [GAUGE] Percent of time all cpus servicing software interrupts\n# TYPE system_cpu_sortirq GAUGE\nsystem_cpu_sortirq{cpu=\"cpu0\"} 0 1635959903645\nsystem_cpu_sortirq{cpu=\"cpu-total\"} 0 1635959903645\n# HELP system_cpu_stolen [GAUGE] Percent of time all cpus serviced virtual hosts operating systems\n# TYPE system_cpu_stolen GAUGE\nsystem_cpu_stolen{cpu=\"cpu0\"} 0 1635959903645\nsystem_cpu_stolen{cpu=\"cpu-total\"} 0 1635959903645\n# HELP system_cpu_guest [GAUGE] Percent of time all cpus serviced guest operating system\n# TYPE system_cpu_guest GAUGE\nsystem_cpu_guest{cpu=\"cpu0\"} 0 1635959903645\nsystem_cpu_guest{cpu=\"cpu-total\"} 0 1635959903645\n# HELP system_cpu_guest_nice [GAUGE] Percent of time all cpus serviced niced guest operating system\n# TYPE system_cpu_guest_nice GAUGE\nsystem_cpu_guest_nice{cpu=\"cpu0\"} 0 1635959903645\nsystem_cpu_guest_nice{cpu=\"cpu-total\"} 0 1635959903645\n# HELP system_mem_used [GAUGE] Percent of memory used\n# TYPE system_mem_used GAUGE\nsystem_mem_used{} 24.63435866529588 1635959903645\n# HELP system_mem_used_bytes [GAUGE] Used memory in bytes\n# TYPE system_mem_used_bytes GAUGE\nsystem_mem_used_bytes{} 2.56159744e+08 1635959903645\n# HELP system_mem_total_bytes [GAUGE] Total memory in bytes\n# TYPE system_mem_total_bytes GAUGE\nsystem_mem_total_bytes{} 1.039847424e+09 1635959903645\n# HELP system_swap_used [GAUGE] Percent of swap used\n# TYPE system_swap_used GAUGE\nsystem_swap_used{} 0.0976564362648702 1635959903645\n# HELP system_swap_used_bytes [GAUGE] Used swap in bytes\n# TYPE system_swap_used_bytes GAUGE\nsystem_swap_used_bytes{} 2.56159744e+08 1635959903645\n# HELP system_swap_total_bytes [GAUGE] Total swap in bytes\n# TYPE system_swap_total_bytes GAUGE\nsystem_swap_total_bytes{} 2.147479552e+09 1635959903645\n# HELP system_load_load1 [GAUGE] System load averaged over 1 minute, high load value dependant on number of cpus in system\n# TYPE system_load_load1 GAUGE\nsystem_load_load1{} 0.09 1635959903645\n# HELP system_load_load5 [GAUGE] System load averaged over 5 minute, high load value dependent on number of cpus in system\n# TYPE system_load_load5 GAUGE\nsystem_load_load5{} 0.04 1635959903645\n# HELP system_load_load15 [GAUGE] System load averaged over 15 minute, high load value dependent on number of cpus in system\n# TYPE system_load_load15 GAUGE\nsystem_load_load15{} 0.05 1635959903645\n# HELP system_load_load1_per_cpu [GAUGE] System load averaged over 1 minute normalized by cpu count, values > 1 means system may be overloaded\n# TYPE system_load_load1_per_cpu GAUGE\nsystem_load_load1_per_cpu{} 0.09 1635959903645\n# HELP system_load_load5_per_cpu [GAUGE] System load averaged over 5 minute normalized by cpu count, values > 1 means system may be overloaded\n# TYPE system_load_load5_per_cpu GAUGE\nsystem_load_load5_per_cpu{} 0.04 1635959903645\n# HELP system_load_load15_per_cpu [GAUGE] System load averaged over 15 minute normalized by cpu count, values > 1 means system may be overloaded\n# TYPE system_load_load15_per_cpu GAUGE\nsystem_load_load15_per_cpu{} 0.05 1635959903645\n# HELP system_host_uptime [COUNTER] Host uptime in seconds\n# TYPE system_host_uptime COUNTER\nsystem_host_uptime{} 15488 1635959903645\n# HELP system_host_processes [GAUGE] Number of host processes\n# TYPE system_host_processes GAUGE\nsystem_host_processes{} 112 1635959903645\n\n", + "output_metric_format": "prometheus_text", + "output_metric_handlers": null, + "pipelines": [], + "processed_by": "sensu-centos", + "proxy_entity_name": "", + "publish": true, + "round_robin": false, + "runtime_assets": [ + "system-check" + ], + "scheduler": "memory", + "secrets": null, + "state": "passing", + "status": 0, + "stdin": false, + "subdue": null, + "subscriptions": [ + "system" + ], + "timeout": 0, + "total_state_change": 0, + "ttl": 0 + }, + "entity": { + "deregister": false, + "deregistration": {}, + "entity_class": "agent", + "last_seen": 1635959903, + "metadata": { + "created_by": "admin", + "name": "sensu-centos", + "namespace": "default" + }, + "redact": [ + "password", + "passwd", + "pass", + "api_key", + "api_token", + "access_key", + "secret_key", + "private_key", + "secret" + ], + "sensu_agent_version": "6.5.4", + "subscriptions": [ + "system", + "entity:sensu-centos", + "webserver" + ], + "system": { + "arch": "amd64", + "cloud_provider": "", + "hostname": "sensu-centos", + "libc_type": "glibc", + "network": { + "interfaces": [ + { + "addresses": [ + "127.0.0.1/8", + ":1/128" + ], + "name": "lo" + }, + { + "addresses": [ + "10.0.2.15/24", + "fe80::20b8:8cea:fa4:2e57/64" + ], + "mac": "08:00:27:8b:c9:3f", + "name": "eth0" + }, + { + "addresses": [ + "192.168.200.95/24", + "fe80::a00:27ff:fe40:ab31/64" + ], + "mac": "08:00:27:40:ab:31", + "name": "eth1" + } + ] + }, + "os": "linux", + "platform": "centos", + "platform_family": "rhel", + "platform_version": "7.9.2009", + "processes": null, + "vm_role": "guest", + "vm_system": "vbox" + }, + "user": "agent" + }, + "id": "07425e48-e163-47d3-8bc8-17fbaa27e469", + "pipelines": null, + "sequence": 122, + "timestamp": 1635959906 + } +} +{{< /code >}} + +{{< /language-toggle >}} + +Metrics data points are not included in events retrieved with sensuctl event info — those events include check output text rather than a set of metrics points. +To view metrics points data as shown in the following example, create a [pipeline][44] workflow that includes a [debug handler][46] that prints events to a JSON file: + +{{< code json >}} +{ + "metrics": { + "points": [ + { + "name": "system_cpu_sortirq", + "value": 0, + "timestamp": 1635952533, + "tags": [ + { + "name": "cpu", + "value": "cpu0" + }, + { + "name": "prom_type", + "value": "gauge" + } + ] + }, + { + "name": "system_cpu_sortirq", + "value": 0, + "timestamp": 1635952533, + "tags": [ + { + "name": "cpu", + "value": "cpu-total" + }, + { + "name": "prom_type", + "value": "gauge" + } + ] + }, + { + "name": "system_cpu_guest", + "value": 0, + "timestamp": 1635952533, + "tags": [ + { + "name": "cpu", + "value": "cpu0" + }, + { + "name": "prom_type", + "value": "gauge" + } + ] + }, + { + "name": "system_cpu_guest", + "value": 0, + "timestamp": 1635952533, + "tags": [ + { + "name": "cpu", + "value": "cpu-total" + }, + { + "name": "prom_type", + "value": "gauge" + } + ] + }, + { + "name": "system_mem_used_bytes", + "value": 260579328, + "timestamp": 1635952533, + "tags": [ + { + "name": "prom_type", + "value": "gauge" + } + ] + }, + { + "name": "system_mem_total_bytes", + "value": 1039847424, + "timestamp": 1635952533, + "tags": [ + { + "name": "prom_type", + "value": "gauge" + } + ] + }, + { + "name": "system_swap_used", + "value": 0.0736237976528123, + "timestamp": 1635952533, + "tags": [ + { + "name": "prom_type", + "value": "gauge" + } + ] + }, + { + "name": "system_cpu_used", + "value": 0.6756756756291793, + "timestamp": 1635952533, + "tags": [ + { + "name": "cpu", + "value": "cpu0" + }, + { + "name": "prom_type", + "value": "gauge" + } + ] + }, + { + "name": "system_cpu_used", + "value": 0.6756756756291793, + "timestamp": 1635952533, + "tags": [ + { + "name": "cpu", + "value": "cpu-total" + }, + { + "name": "prom_type", + "value": "gauge" + } + ] + }, + { + "name": "system_cpu_nice", + "value": 0, + "timestamp": 1635952533, + "tags": [ + { + "name": "cpu", + "value": "cpu0" + }, + { + "name": "prom_type", + "value": "gauge" + } + ] + }, + { + "name": "system_cpu_nice", + "value": 0, + "timestamp": 1635952533, + "tags": [ + { + "name": "cpu", + "value": "cpu-total" + }, + { + "name": "prom_type", + "value": "gauge" + } + ] + }, + { + "name": "system_cpu_irq", + "value": 0, + "timestamp": 1635952533, + "tags": [ + { + "name": "cpu", + "value": "cpu0" + }, + { + "name": "prom_type", + "value": "gauge" + } + ] + }, + { + "name": "system_cpu_irq", + "value": 0, + "timestamp": 1635952533, + "tags": [ + { + "name": "cpu", + "value": "cpu-total" + }, + { + "name": "prom_type", + "value": "gauge" + } + ] + }, + { + "name": "system_load_load1", + "value": 0.01, + "timestamp": 1635952533, + "tags": [ + { + "name": "prom_type", + "value": "gauge" + } + ] + }, + { + "name": "system_host_uptime", + "value": 10642, + "timestamp": 1635952533, + "tags": [ + { + "name": "prom_type", + "value": "counter" + } + ] + }, + { + "name": "system_host_processes", + "value": 116, + "timestamp": 1635952533, + "tags": [ + { + "name": "prom_type", + "value": "gauge" + } + ] + }, + { + "name": "system_load_load5_per_cpu", + "value": 0.02, + "timestamp": 1635952533, + "tags": [ + { + "name": "prom_type", + "value": "gauge" + } + ] + }, + { + "name": "system_cpu_cores", + "value": 1, + "timestamp": 1635952533, + "tags": [ + { + "name": "prom_type", + "value": "gauge" + } + ] + }, + { + "name": "system_swap_used_bytes", + "value": 260579328, + "timestamp": 1635952533, + "tags": [ + { + "name": "prom_type", + "value": "gauge" + } + ] + }, + { + "name": "system_load_load5", + "value": 0.02, + "timestamp": 1635952533, + "tags": [ + { + "name": "prom_type", + "value": "gauge" + } + ] + }, + { + "name": "system_mem_used", + "value": 25.059381019344624, + "timestamp": 1635952533, + "tags": [ + { + "name": "prom_type", + "value": "gauge" + } + ] + }, + { + "name": "system_swap_total_bytes", + "value": 2147479552, + "timestamp": 1635952533, + "tags": [ + { + "name": "prom_type", + "value": "gauge" + } + ] + }, + { + "name": "system_load_load1_per_cpu", + "value": 0.01, + "timestamp": 1635952533, + "tags": [ + { + "name": "prom_type", + "value": "gauge" + } + ] + }, + { + "name": "system_load_load15_per_cpu", + "value": 0.05, + "timestamp": 1635952533, + "tags": [ + { + "name": "prom_type", + "value": "gauge" + } + ] + }, + { + "name": "system_cpu_idle", + "value": 99.32432432437082, + "timestamp": 1635952533, + "tags": [ + { + "name": "prom_type", + "value": "gauge" + }, + { + "name": "cpu", + "value": "cpu0" + } + ] + }, + { + "name": "system_cpu_idle", + "value": 99.32432432437082, + "timestamp": 1635952533, + "tags": [ + { + "name": "cpu", + "value": "cpu-total" + }, + { + "name": "prom_type", + "value": "gauge" + } + ] + }, + { + "name": "system_cpu_user", + "value": 0.3378378378376302, + "timestamp": 1635952533, + "tags": [ + { + "name": "cpu", + "value": "cpu0" + }, + { + "name": "prom_type", + "value": "gauge" + } + ] + }, + { + "name": "system_cpu_user", + "value": 0.3378378378376302, + "timestamp": 1635952533, + "tags": [ + { + "name": "cpu", + "value": "cpu-total" + }, + { + "name": "prom_type", + "value": "gauge" + } + ] + }, + { + "name": "system_cpu_iowait", + "value": 0, + "timestamp": 1635952533, + "tags": [ + { + "name": "cpu", + "value": "cpu0" + }, + { + "name": "prom_type", + "value": "gauge" + } + ] + }, + { + "name": "system_cpu_iowait", + "value": 0, + "timestamp": 1635952533, + "tags": [ + { + "name": "cpu", + "value": "cpu-total" + }, + { + "name": "prom_type", + "value": "gauge" + } + ] + }, + { + "name": "system_load_load15", + "value": 0.05, + "timestamp": 1635952533, + "tags": [ + { + "name": "prom_type", + "value": "gauge" + } + ] + }, + { + "name": "system_cpu_system", + "value": 0.3378378378376302, + "timestamp": 1635952533, + "tags": [ + { + "name": "prom_type", + "value": "gauge" + }, + { + "name": "cpu", + "value": "cpu0" + } + ] + }, + { + "name": "system_cpu_system", + "value": 0.3378378378376302, + "timestamp": 1635952533, + "tags": [ + { + "name": "cpu", + "value": "cpu-total" + }, + { + "name": "prom_type", + "value": "gauge" + } + ] + }, + { + "name": "system_cpu_stolen", + "value": 0, + "timestamp": 1635952533, + "tags": [ + { + "name": "cpu", + "value": "cpu0" + }, + { + "name": "prom_type", + "value": "gauge" + } + ] + }, + { + "name": "system_cpu_stolen", + "value": 0, + "timestamp": 1635952533, + "tags": [ + { + "name": "prom_type", + "value": "gauge" + }, + { + "name": "cpu", + "value": "cpu-total" + } + ] + }, + { + "name": "system_cpu_guest_nice", + "value": 0, + "timestamp": 1635952533, + "tags": [ + { + "name": "cpu", + "value": "cpu0" + }, + { + "name": "prom_type", + "value": "gauge" + } + ] + }, + { + "name": "system_cpu_guest_nice", + "value": 0, + "timestamp": 1635952533, + "tags": [ + { + "name": "cpu", + "value": "cpu-total" + }, + { + "name": "prom_type", + "value": "gauge" + } + ] + } + ] + }, + "metadata": { + "namespace": "default" + }, + "id": "afdeb823-74c2-4921-891a-465a2095cb5a", + "sequence": 6, + "pipelines": [ + { + "api_version": "core/v2", + "type": "Pipeline", + "name": "debug_pipeline" + } + ], + "timestamp": 1635952536, + "entity": { + "entity_class": "agent", + "system": { + "hostname": "sensu-centos", + "os": "linux", + "platform": "centos", + "platform_family": "rhel", + "platform_version": "7.9.2009", + "network": { + "interfaces": [ + { + "name": "lo", + "addresses": [ + "127.0.0.1/8", + "::1/128" + ] + }, + { + "name": "eth0", + "mac": "08:00:27:8b:c9:3f", + "addresses": [ + "10.0.2.15/24", + "fe80::20b8:8cea:fa4:2e57/64" + ] + }, + { + "name": "eth1", + "mac": "08:00:27:40:ab:31", + "addresses": [ + "192.168.200.95/24", + "fe80::a00:27ff:fe40:ab31/64" + ] + } + ] + }, + "arch": "amd64", + "libc_type": "glibc", + "vm_system": "vbox", + "vm_role": "guest", + "cloud_provider": "", + "processes": null + }, + "subscriptions": [ + "system", + "entity:sensu-centos" + ], + "last_seen": 1635952533, + "deregister": false, + "deregistration": {}, + "user": "agent", + "redact": [ + "password", + "passwd", + "pass", + "api_key", + "api_token", + "access_key", + "secret_key", + "private_key", + "secret" + ], + "metadata": { + "name": "sensu-centos", + "namespace": "default" + }, + "sensu_agent_version": "6.5.4" + }, + "check": { + "command": "system-check", + "handlers": [], + "high_flap_threshold": 0, + "interval": 10, + "low_flap_threshold": 0, + "publish": true, + "runtime_assets": [ + "system-check" + ], + "subscriptions": [ + "system" + ], + "proxy_entity_name": "", + "check_hooks": null, + "stdin": false, + "subdue": null, + "ttl": 0, + "timeout": 0, + "round_robin": false, + "duration": 3.01062768, + "executed": 1635952533, + "history": [ + { + "status": 0, + "executed": 1635952283 + }, + { + "status": 0, + "executed": 1635952293 + }, + { + "status": 0, + "executed": 1635952303 + }, + { + "status": 0, + "executed": 1635952313 + }, + { + "status": 0, + "executed": 1635952421 + }, + { + "status": 0, + "executed": 1635952533 + } + ], + "issued": 1635952533, + "output": "# HELP system_cpu_cores [GAUGE] Number of cpu cores on the system\n# TYPE system_cpu_cores GAUGE\nsystem_cpu_cores{} 1 1635952533657\n# HELP system_cpu_idle [GAUGE] Percent of time all cpus were idle\n# TYPE system_cpu_idle GAUGE\nsystem_cpu_idle{cpu=\"cpu0\"} 99.32432432437082 1635952533657\nsystem_cpu_idle{cpu=\"cpu-total\"} 99.32432432437082 1635952533657\n# HELP system_cpu_used [GAUGE] Percent of time all cpus were used\n# TYPE system_cpu_used GAUGE\nsystem_cpu_used{cpu=\"cpu0\"} 0.6756756756291793 1635952533657\nsystem_cpu_used{cpu=\"cpu-total\"} 0.6756756756291793 1635952533657\n# HELP system_cpu_user [GAUGE] Percent of time total cpu was used by normal processes in user mode\n# TYPE system_cpu_user GAUGE\nsystem_cpu_user{cpu=\"cpu0\"} 0.3378378378376302 1635952533657\nsystem_cpu_user{cpu=\"cpu-total\"} 0.3378378378376302 1635952533657\n# HELP system_cpu_system [GAUGE] Percent of time all cpus used by processes executed in kernel mode\n# TYPE system_cpu_system GAUGE\nsystem_cpu_system{cpu=\"cpu0\"} 0.3378378378376302 1635952533657\nsystem_cpu_system{cpu=\"cpu-total\"} 0.3378378378376302 1635952533657\n# HELP system_cpu_nice [GAUGE] Percent of time all cpus used by niced processes in user mode\n# TYPE system_cpu_nice GAUGE\nsystem_cpu_nice{cpu=\"cpu0\"} 0 1635952533657\nsystem_cpu_nice{cpu=\"cpu-total\"} 0 1635952533657\n# HELP system_cpu_iowait [GAUGE] Percent of time all cpus waiting for I/O to complete\n# TYPE system_cpu_iowait GAUGE\nsystem_cpu_iowait{cpu=\"cpu0\"} 0 1635952533657\nsystem_cpu_iowait{cpu=\"cpu-total\"} 0 1635952533657\n# HELP system_cpu_irq [GAUGE] Percent of time all cpus servicing interrupts\n# TYPE system_cpu_irq GAUGE\nsystem_cpu_irq{cpu=\"cpu0\"} 0 1635952533657\nsystem_cpu_irq{cpu=\"cpu-total\"} 0 1635952533657\n# HELP system_cpu_sortirq [GAUGE] Percent of time all cpus servicing software interrupts\n# TYPE system_cpu_sortirq GAUGE\nsystem_cpu_sortirq{cpu=\"cpu0\"} 0 1635952533657\nsystem_cpu_sortirq{cpu=\"cpu-total\"} 0 1635952533657\n# HELP system_cpu_stolen [GAUGE] Percent of time all cpus serviced virtual hosts operating systems\n# TYPE system_cpu_stolen GAUGE\nsystem_cpu_stolen{cpu=\"cpu0\"} 0 1635952533657\nsystem_cpu_stolen{cpu=\"cpu-total\"} 0 1635952533657\n# HELP system_cpu_guest [GAUGE] Percent of time all cpus serviced guest operating system\n# TYPE system_cpu_guest GAUGE\nsystem_cpu_guest{cpu=\"cpu0\"} 0 1635952533657\nsystem_cpu_guest{cpu=\"cpu-total\"} 0 1635952533657\n# HELP system_cpu_guest_nice [GAUGE] Percent of time all cpus serviced niced guest operating system\n# TYPE system_cpu_guest_nice GAUGE\nsystem_cpu_guest_nice{cpu=\"cpu0\"} 0 1635952533657\nsystem_cpu_guest_nice{cpu=\"cpu-total\"} 0 1635952533657\n# HELP system_mem_used [GAUGE] Percent of memory used\n# TYPE system_mem_used GAUGE\nsystem_mem_used{} 25.059381019344624 1635952533657\n# HELP system_mem_used_bytes [GAUGE] Used memory in bytes\n# TYPE system_mem_used_bytes GAUGE\nsystem_mem_used_bytes{} 2.60579328e+08 1635952533657\n# HELP system_mem_total_bytes [GAUGE] Total memory in bytes\n# TYPE system_mem_total_bytes GAUGE\nsystem_mem_total_bytes{} 1.039847424e+09 1635952533657\n# HELP system_swap_used [GAUGE] Percent of swap used\n# TYPE system_swap_used GAUGE\nsystem_swap_used{} 0.0736237976528123 1635952533657\n# HELP system_swap_used_bytes [GAUGE] Used swap in bytes\n# TYPE system_swap_used_bytes GAUGE\nsystem_swap_used_bytes{} 2.60579328e+08 1635952533657\n# HELP system_swap_total_bytes [GAUGE] Total swap in bytes\n# TYPE system_swap_total_bytes GAUGE\nsystem_swap_total_bytes{} 2.147479552e+09 1635952533657\n# HELP system_load_load1 [GAUGE] System load averaged over 1 minute, high load value dependant on number of cpus in system\n# TYPE system_load_load1 GAUGE\nsystem_load_load1{} 0.01 1635952533657\n# HELP system_load_load5 [GAUGE] System load averaged over 5 minute, high load value dependent on number of cpus in system\n# TYPE system_load_load5 GAUGE\nsystem_load_load5{} 0.02 1635952533657\n# HELP system_load_load15 [GAUGE] System load averaged over 15 minute, high load value dependent on number of cpus in system\n# TYPE system_load_load15 GAUGE\nsystem_load_load15{} 0.05 1635952533657\n# HELP system_load_load1_per_cpu [GAUGE] System load averaged over 1 minute normalized by cpu count, values \\u003e 1 means system may be overloaded\n# TYPE system_load_load1_per_cpu GAUGE\nsystem_load_load1_per_cpu{} 0.01 1635952533657\n# HELP system_load_load5_per_cpu [GAUGE] System load averaged over 5 minute normalized by cpu count, values \\u003e 1 means system may be overloaded\n# TYPE system_load_load5_per_cpu GAUGE\nsystem_load_load5_per_cpu{} 0.02 1635952533657\n# HELP system_load_load15_per_cpu [GAUGE] System load averaged over 15 minute normalized by cpu count, values \\u003e 1 means system may be overloaded\n# TYPE system_load_load15_per_cpu GAUGE\nsystem_load_load15_per_cpu{} 0.05 1635952533657\n# HELP system_host_uptime [COUNTER] Host uptime in seconds\n# TYPE system_host_uptime COUNTER\nsystem_host_uptime{} 10642 1635952533657\n# HELP system_host_processes [GAUGE] Number of host processes\n# TYPE system_host_processes GAUGE\nsystem_host_processes{} 116 1635952533657\n\n", + "state": "passing", + "status": 0, + "total_state_change": 0, + "last_ok": 1635952533, + "occurrences": 6, + "occurrences_watermark": 6, + "output_metric_format": "prometheus_text", + "output_metric_handlers": null, + "env_vars": null, + "metadata": { + "name": "system-check", + "namespace": "default", + "labels": { + "sensu.io/managed_by": "sensuctl" + } + }, + "secrets": null, + "is_silenced": false, + "scheduler": "memory", + "processed_by": "sensu-centos", + "pipelines": [], + "output_metric_thresholds": [ + { + "name": "system_mem_used", + "tags": null, + "null_status": 1, + "thresholds": [ + { + "min": "", + "max": "75.0", + "status": 1 + }, + { + "min": "", + "max": "90.0", + "status": 2 + } + ] + }, + { + "name": "system_host_processes", + "tags": [ + { + "name": "namespace", + "value": "production" + } + ], + "null_status": 1, + "thresholds": [ + { + "min": "5", + "max": "50", + "status": 1 + }, + { + "min": "2", + "max": "75", + "status": 2 + } + ] + } + ] + } +} +{{< /code >}} + +## Example status and metrics event + +The following example resource definition for a [status and metrics event][19] contains _both_ a check and metrics, retrieved with sensuctl event info: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Event +api_version: core/v2 +metadata: + namespace: default +spec: + check: + check_hooks: null + command: http-check --url http://localhost && http-perf --url http://localhost + --warning 1s --critical 2s + duration: 0.022274319 + env_vars: null + executed: 1635959379 + handlers: null + high_flap_threshold: 0 + history: + - executed: 1635952820 + status: 0 + - executed: 1635952835 + status: 0 + - executed: 1635952850 + status: 0 + - executed: 1635952865 + status: 0 + - executed: 1635952880 + status: 0 + interval: 5 + is_silenced: false + issued: 1635952880 + last_ok: 1635952880 + low_flap_threshold: 0 + metadata: + name: collect-metrics + namespace: default + occurrences: 5 + occurrences_watermark: 5 + output: | + http-check OK: HTTP Status 200 for http://localhost + http-perf OK: 0.001150s | dns_duration=0.000257, tls_handshake_duration=0.000000, connect_duration=0.000088, first_byte_duration=0.001131, total_request_duration=0.001150 + output_metric_format: nagios_perfdata + output_metric_handlers: null + pipelines: [] + processed_by: sensu-centos + proxy_entity_name: "" + publish: true + round_robin: false + runtime_assets: + - http-checks + scheduler: memory + secrets: null + state: passing + status: 0 + stdin: false + subdue: null + subscriptions: + - webserver + timeout: 0 + total_state_change: 0 + ttl: 0 + entity: + deregister: false + deregistration: {} + entity_class: agent + last_seen: 1635959379 + metadata: + created_by: admin + name: sensu-centos + namespace: default + redact: + - password + - passwd + - pass + - api_key + - api_token + - access_key + - secret_key + - private_key + - secret + sensu_agent_version: 6.5.4 + subscriptions: + - system + - entity:sensu-centos + - webserver + system: + arch: amd64 + cloud_provider: "" + hostname: sensu-centos + libc_type: glibc + network: + interfaces: + - addresses: + - 127.0.0.1/8 + - ::1/128 + name: lo + - addresses: + - 10.0.2.15/24 + - fe80::20b8:8cea:fa4:2e57/64 + mac: 08:00:27:8b:c9:3f + name: eth0 + - addresses: + - 192.168.200.95/24 + - fe80::a00:27ff:fe40:ab31/64 + mac: 08:00:27:40:ab:31 + name: eth1 + os: linux + platform: centos + platform_family: rhel + platform_version: 7.9.2009 + processes: null + vm_role: guest + vm_system: vbox + user: agent + id: 12545deb-0e0f-480f-addf-34545d5a01c6 + pipelines: + - type: Pipeline + api_version: core/v2 + name: status_and_metrics_pipeline + sequence: 5 + timestamp: 1635952880 +{{< /code >}} + +{{< code json >}} +{ + "type": "Event", + "api_version": "core/v2", + "metadata": { + "namespace": "default" + }, + "spec": { + "check": { + "check_hooks": null, + "command": "http-check --url http://localhost && http-perf --url http://localhost --warning 1s --critical 2s", + "duration": 0.022274319, + "env_vars": null, + "executed": 1635959379, + "handlers": null, + "high_flap_threshold": 0, + "history": [ + { + "executed": 1635952820, + "status": 0 + }, + { + "executed": 1635952835, + "status": 0 + }, + { + "executed": 1635952850, + "status": 0 + }, + { + "executed": 1635952865, + "status": 0 + }, + { + "executed": 1635952880, + "status": 0 + } + ], + "interval": 5, + "is_silenced": false, + "issued": 1635952880, + "last_ok": 1635952880, + "low_flap_threshold": 0, + "metadata": { + "name": "collect-metrics", + "namespace": "default" + }, + "occurrences": 5, + "occurrences_watermark": 5, + "output": "http-check OK: HTTP Status 200 for http://localhost\nhttp-perf OK: 0.001150s | dns_duration=0.000257, tls_handshake_duration=0.000000, connect_duration=0.000088, first_byte_duration=0.001131, total_request_duration=0.001150\n", + "output_metric_format": "nagios_perfdata", + "output_metric_handlers": null, + "pipelines": [], + "processed_by": "sensu-centos", + "proxy_entity_name": "", + "publish": true, + "round_robin": false, + "runtime_assets": [ + "http-checks" + ], + "scheduler": "memory", + "secrets": null, + "state": "passing", + "status": 0, + "stdin": false, + "subdue": null, + "subscriptions": [ + "webserver" + ], + "timeout": 0, + "total_state_change": 0, + "ttl": 0 + }, + "entity": { + "deregister": false, + "deregistration": {}, + "entity_class": "agent", + "last_seen": 1635959379, + "metadata": { + "created_by": "admin", + "name": "sensu-centos", + "namespace": "default" + }, + "redact": [ + "password", + "passwd", + "pass", + "api_key", + "api_token", + "access_key", + "secret_key", + "private_key", + "secret" + ], + "sensu_agent_version": "6.5.4", + "subscriptions": [ + "system", + "entity:sensu-centos", + "webserver" + ], + "system": { + "arch": "amd64", + "cloud_provider": "", + "hostname": "sensu-centos", + "libc_type": "glibc", + "network": { + "interfaces": [ + { + "addresses": [ + "127.0.0.1/8", + ":1/128" + ], + "name": "lo" + }, + { + "addresses": [ + "10.0.2.15/24", + "fe80::20b8:8cea:fa4:2e57/64" + ], + "mac": "08:00:27:8b:c9:3f", + "name": "eth0" + }, + { + "addresses": [ + "192.168.200.95/24", + "fe80::a00:27ff:fe40:ab31/64" + ], + "mac": "08:00:27:40:ab:31", + "name": "eth1" + } + ] + }, + "os": "linux", + "platform": "centos", + "platform_family": "rhel", + "platform_version": "7.9.2009", + "processes": null, + "vm_role": "guest", + "vm_system": "vbox" + }, + "user": "agent" + }, + "id": "12545deb-0e0f-480f-addf-34545d5a01c6", + "pipelines": [ + { + "type": "Pipeline", + "api_version": "core/v2", + "name": "status_and_metrics_pipeline" + } + ], + "sequence": 5, + "timestamp": 1635952880 + } +} +{{< /code >}} + +{{< /language-toggle >}} + +Metrics data points are not included in events retrieved with sensuctl event info — those events include check output text rather than a set of metrics points. +To view metrics points data as shown in the following example, create a [pipeline][44] workflow that includes a [debug handler][46] that prints events to a JSON file: + +{{< code json >}} +{ + "entity": { + "entity_class": "agent", + "system": { + "hostname": "sensu-centos", + "os": "linux", + "platform": "centos", + "platform_family": "rhel", + "platform_version": "7.9.2009", + "network": { + "interfaces": [ + { + "name": "lo", + "addresses": [ + "127.0.0.1/8", + "::1/128" + ] + }, + { + "name": "eth0", + "mac": "08:00:27:8b:c9:3f", + "addresses": [ + "10.0.2.15/24", + "fe80::20b8:8cea:fa4:2e57/64" + ] + }, + { + "name": "eth1", + "mac": "08:00:27:40:ab:31", + "addresses": [ + "192.168.200.95/24", + "fe80::a00:27ff:fe40:ab31/64" + ] + } + ] + }, + "arch": "amd64", + "libc_type": "glibc", + "vm_system": "vbox", + "vm_role": "guest", + "cloud_provider": "", + "processes": null + }, + "subscriptions": [ + "system", + "entity:sensu-centos", + "webserver" + ], + "last_seen": 1635952880, + "deregister": false, + "deregistration": {}, + "user": "agent", + "redact": [ + "password", + "passwd", + "pass", + "api_key", + "api_token", + "access_key", + "secret_key", + "private_key", + "secret" + ], + "metadata": { + "name": "sensu-centos", + "namespace": "default", + "created_by": "admin" + }, + "sensu_agent_version": "6.5.4" + }, + "check": { + "command": "http-check --url http://localhost \\u0026\\u0026 http-perf --url http://localhost --warning 1s --critical 2s", + "handlers": [], + "high_flap_threshold": 0, + "interval": 15, + "low_flap_threshold": 0, + "publish": true, + "runtime_assets": [ + "http-checks" + ], + "subscriptions": [ + "webserver" + ], + "proxy_entity_name": "", + "check_hooks": null, + "stdin": false, + "subdue": null, + "ttl": 0, + "timeout": 0, + "round_robin": false, + "duration": 0.018747388, + "executed": 1635952880, + "history": [ + { + "status": 0, + "executed": 1635952820 + }, + { + "status": 0, + "executed": 1635952835 + }, + { + "status": 0, + "executed": 1635952850 + }, + { + "status": 0, + "executed": 1635952865 + }, + { + "status": 0, + "executed": 1635952880 + } + ], + "issued": 1635952880, + "output": "http-check OK: HTTP Status 200 for http://localhost\nhttp-perf OK: 0.001059s | dns_duration=0.000235, tls_handshake_duration=0.000000, connect_duration=0.000083, first_byte_duration=0.001040, total_request_duration=0.001059\n", + "state": "passing", + "status": 0, + "total_state_change": 0, + "last_ok": 1635952880, + "occurrences": 5, + "occurrences_watermark": 5, + "output_metric_format": "nagios_perfdata", + "output_metric_handlers": null, + "env_vars": null, + "metadata": { + "name": "collect-metrics", + "namespace": "default" + }, + "secrets": null, + "is_silenced": false, + "scheduler": "memory", + "processed_by": "sensu-centos", + "pipelines": [] + }, + "metrics": { + "points": [ + { + "name": "dns_duration", + "value": 0.000235, + "timestamp": 1635952880, + "tags": null + }, + { + "name": "tls_handshake_duration", + "value": 0, + "timestamp": 1635952880, + "tags": null + }, + { + "name": "connect_duration", + "value": 0.000083, + "timestamp": 1635952880, + "tags": null + }, + { + "name": "first_byte_duration", + "value": 0.00104, + "timestamp": 1635952880, + "tags": null + }, + { + "name": "total_request_duration", + "value": 0.001059, + "timestamp": 1635952880, + "tags": null + } + ] + }, + "metadata": { + "namespace": "default" + }, + "id": "7cde3e3f-beee-408f-b89a-1edccd0d3edb", + "sequence": 5, + "pipelines": [ + { + "type": "Pipeline", + "api_version": "core/v2", + "name": "debug_pipeline" + } + ], + "timestamp": 1635952880 +} +{{< /code >}} + +## Create events using the Sensu agent + +The Sensu agent is a powerful event producer and monitoring automation tool. +You can use Sensu agents to produce events automatically using service checks and metric checks. +Sensu agents can also act as a collector for metrics throughout your infrastructure. + +- [Create events using service checks][10] +- [Create events using metric checks][6] +- [Create events using the agent API][11] +- [Create events using the agent TCP and UDP sockets][12] +- [Create events using the StatsD listener][13] + +## Create events with the core/v2/events API endpoints + +You can send events directly to the Sensu observability pipeline using the [core/v2 API events endpoint][16]. +To create an event, send a JSON event definition with a [PUT request to core/v2/events][14]. + +If you use the core/v2/events API to create a new event referencing an entity that does not already exist, the sensu-backend will automatically create a proxy entity in the same namespace when the event is published. + +{{% notice note %}} +**NOTE**: An agent cannot belong to, execute checks in, or create events in more than one namespace. +{{% /notice %}} + +## Manage events + +You can manage events using the [Sensu web UI][15], [core/v2/events API endpoints][16], and [sensuctl][17] command line tool. + +### View events + +To list all events: + +{{< code shell >}} +sensuctl event list +{{< /code >}} + +To show event details in the default [output format][18] (tabular): + +{{< code shell >}} +sensuctl event info +{{< /code >}} + +{{% notice note %}} +**NOTE**: Metrics data points are not included in events retrieved with `sensuctl event info` — these events include check output text rather than a set of metrics points. +{{% /notice %}} + +With both the `list` and `info` commands, you can specify an [output format][18] using the `--format` flag: + +- `yaml` or `wrapped-json` formats for use with [`sensuctl create`][8] +- `json` format for use with [core/v2/events API endpoints][16] + +{{< language-toggle >}} +{{< code shell "YML" >}} +sensuctl event info entity-name check-name --format yaml +{{< /code >}} +{{< code shell "Wrapped JSON" >}} +sensuctl event info entity-name check-name --format wrapped-json +{{< /code >}} +{{< code shell "JSON" >}} +sensuctl event info entity-name check-name --format json +{{< /code >}} +{{< /language-toggle >}} + +{{% notice protip %}} +**PRO TIP**: You can also [view complete resource definitions in the Sensu web UI](../../../web-ui/view-manage-resources/#view-resource-data-in-the-web-ui). +{{% /notice %}} + +### Delete events + +To delete an event: + +{{< code shell >}} +sensuctl event delete entity-name check-name +{{< /code >}} + +You can use the `--skip-confirm` flag to skip the confirmation step: + +{{< code shell >}} +sensuctl event delete entity-name check-name --skip-confirm +{{< /code >}} + +You should receive a confirmation message upon success: + +{{< code text >}} +Deleted +{{< /code >}} + +### Resolve events + +You can use sensuctl to change the status of an event to `0` (OK). +Events resolved by sensuctl include the output message `Resolved manually by sensuctl`. + +{{< code shell >}} +sensuctl event resolve entity-name check-name +{{< /code >}} + +You should receive a confirmation message upon success: + +{{< code text >}} +Resolved +{{< /code >}} + +## Use event data + +Observability data in events is a powerful tool for automating monitoring workflows. +For example, the [`state` attribute][36] provides handlers with a high-level description of check status. +Filtering events based on this attribute can help [reduce alert fatigue][23]. + +### State attribute + +The `state` event attribute adds meaning to the check status: + +- `passing` means the check status is `0` (OK). +- `failing` means the check status is non-zero (WARNING or CRITICAL). +- `flapping` indicates an unsteady state in which the check result status (determined based on per-check [high flap threshold][37] and [low flap threshold][47] attributes) is not settling on `passing` or `failing` according to the [flap detection algorithm][39]. + +Flapping typically indicates intermittent problems with an entity, provided your low and high flap threshold settings are properly configured. +Although some teams choose to filter out flapping events to reduce unactionable alerts, we suggest sending flapping events to a designated handler for later review. +If you repeatedly observe events in flapping state, Sensu's per-check flap threshold configuration allows you to adjust the sensitivity of the [flap detection algorithm][39]. + +#### Flap detection algorithm + +Sensu uses the same flap detection algorithm as [Nagios][38]. +Every time you run a check, Sensu records whether the `status` value changed since the previous check. +Sensu stores the last 21 `status` values and uses them to calculate the percent state change for the entity/check pair. +Then, Sensu's algorithm applies a weight to these status changes: more recent changes have more value than older changes. + +After calculating the weighted total percent state change, Sensu compares it with the [high flap threshold][37] and [low flap threshold][47] set in the check attributes. + +- If the entity was **not** already flapping and the weighted total percent state change for the entity/check pair is greater than or equal to the `high_flap_threshold` setting, the entity has started flapping. +- If the entity **was** already flapping and the weighted total percent state change for the entity/check pair is less than the `low_flap_threshold` setting, the entity has stopped flapping. + +Depending on the result of this comparison, Sensu will trigger the appropriate event filters based on [check attributes][40] like `event.check.high_flap_threshold` and `event.check.low_flap_threshold`. + +### Occurrences and occurrences watermark + +The `occurrences` and `occurrences_watermark` event attributes give you context about recent events for a given entity and check. +You can use these attributes within [event filters][24] to fine-tune incident notifications and reduce alert fatigue. + +Starting at `1`, the `occurrences` attribute increments for events with the same [status][25] as the preceding event (OK, WARNING, CRITICAL, or UNKNOWN) and resets whenever the status changes. +You can use the `occurrences` attribute to create a [state-change-only filter][27] or an [interval filter][28]. + +The `occurrences_watermark` attribute gives you useful information when looking at events that change status between non-OK (WARNING, CRITICAL, or UNKNOWN) and OK. +For these resolution events, the `occurrences_watermark` attribute tells you the number of preceding events with a non-OK status. +Sensu resets `occurrences_watermark` to `1` on the first non-OK event. +Within a sequence of only OK or only non-OK events, Sensu increments `occurrences_watermark` when the `occurrences` attribute is greater than the preceding `occurrences_watermark`. + +The following table shows the occurrences attributes for a series of example events: + +| event sequence | `occurrences` | `occurrences_watermark` | +| ----------------- | --------------- | ----------------------- | +|1. OK event | `occurrences: 1`| `occurrences_watermark: 1` +|2. OK event | `occurrences: 2`| `occurrences_watermark: 2` +|3. WARNING event | `occurrences: 1`| `occurrences_watermark: 1` +|4. WARNING event | `occurrences: 2`| `occurrences_watermark: 2` +|5. WARNING event | `occurrences: 3`| `occurrences_watermark: 3` +|6. CRITICAL event | `occurrences: 1`| `occurrences_watermark: 3` +|7. CRITICAL event | `occurrences: 2`| `occurrences_watermark: 3` +|8. CRITICAL event | `occurrences: 3`| `occurrences_watermark: 3` +|9. CRITICAL event | `occurrences: 4`| `occurrences_watermark: 4` +|10. OK event | `occurrences: 1`| `occurrences_watermark: 4` +|11. CRITICAL event | `occurrences: 1`| `occurrences_watermark: 1` + +## Event specification + +### Top-level attributes + +api_version | +-------------|------ +description | Top-level attribute that specifies the Sensu API group and version. For events in this version of Sensu, `api_version` should always be `core/v2`. +required | Required for events in `wrapped-json` or `yaml` format for use with [`sensuctl create`][8]. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +api_version: core/v2 +{{< /code >}} +{{< code json >}} +{ + "api_version": "core/v2" +} +{{< /code >}} +{{< /language-toggle >}} + +metadata | +-------------|------ +description | Top-level scope that contains the event `namespace` and `created_by` field. The `metadata` map is always at the top level of the check definition. This means that in `wrapped-json` and `yaml` formats, the `metadata` scope occurs outside the `spec` scope. Review the [metadata attributes][29] for details. +required | Required for events in `wrapped-json` or `yaml` format for use with [`sensuctl create`][8]. +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +metadata: + namespace: default + created_by: admin +{{< /code >}} +{{< code json >}} +{ + "metadata": { + "namespace": "default", + "created_by": "admin" + } +} +{{< /code >}} +{{< /language-toggle >}} + + + +| pipelines | | +-------------|------ +description | Name, type, and API version for the [pipelines][44] used to process the observability event. Sensu automatically populates the pipelines attributes when the event is created or updated. Read [pipelines attributes][45] for more information. +required | false +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +pipelines: +- type: Pipeline + api_version: core/v2 + name: incident_alerts +{{< /code >}} +{{< code json >}} +{ + "pipelines": [ + { + "type": "Pipeline", + "api_version": "core/v2", + "name": "incident_alerts" + } + ] +} +{{< /code >}} +{{< /language-toggle >}} + +spec | +-------------|------ +description | Top-level map that includes the event [spec attributes][9]. +required | Required for events in `wrapped-json` or `yaml` format for use with [`sensuctl create`][8]. +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +spec: + check: + check_hooks: + command: metrics-curl -u "http://localhost" + duration: 0.060790838 + env_vars: + executed: 1552506033 + handlers: [] + high_flap_threshold: 0 + history: + - executed: 1552505833 + status: 0 + - executed: 1552505843 + status: 0 + interval: 10 + is_silenced: true + processed_by: sensu-go-sandbox + issued: 1552506033 + last_ok: 1552506033 + low_flap_threshold: 0 + metadata: + name: curl_timings + namespace: default + occurrences: 1 + occurrences_watermark: 1 + silenced: + - webserver:* + output: |- + sensu-go.curl_timings.time_total 0.005 1552506033 + sensu-go.curl_timings.time_namelookup 0.004 + output_metric_format: graphite_plaintext + proxy_entity_name: '' + publish: true + round_robin: false + runtime_assets: [] + state: passing + status: 0 + stdin: false + subdue: + subscriptions: + - entity:sensu-go-testing + timeout: 0 + total_state_change: 0 + ttl: 0 + entity: + deregister: false + deregistration: {} + entity_class: agent + last_seen: 1552495139 + metadata: + name: sensu-go-testing + namespace: default + redact: + - password + - passwd + - pass + - api_key + - api_token + - access_key + - secret_key + - private_key + - secret + subscriptions: + - entity:sensu-go-testing + system: + arch: amd64 + hostname: sensu-go-testing + network: + interfaces: + - addresses: + - 127.0.0.1/8 + - "::1/128" + name: lo + - addresses: + - 10.0.2.15/24 + - fe80::5a94:f67a:1bfc:a579/64 + mac: '08:00:27:8b:c9:3f' + name: eth0 + os: linux + platform: centos + platform_family: rhel + platform_version: 7.5.1804 + processes: + user: agent + metrics: + points: + - name: sensu-go.curl_timings.time_total + tags: [] + timestamp: 1552506033 + value: 0.005 + - name: sensu-go.curl_timings.time_namelookup + tags: [] + timestamp: 1552506033 + value: 0.004 + pipelines: + - type: Pipeline + api_version: core/v2 + name: status_and_metrics_pipeline + timestamp: 1552506033 + id: 431a0085-96da-4521-863f-c38b480701e9 + sequence: 1 +{{< /code >}} +{{< code json >}} +{ + "spec": { + "check": { + "check_hooks": null, + "command": "metrics-curl -u \"http://localhost\"", + "duration": 0.060790838, + "env_vars": null, + "executed": 1552506033, + "handlers": [], + "high_flap_threshold": 0, + "history": [ + { + "executed": 1552505833, + "status": 0 + }, + { + "executed": 1552505843, + "status": 0 + } + ], + "interval": 10, + "is_silenced": true, + "processed_by": "sensu-go-sandbox", + "issued": 1552506033, + "last_ok": 1552506033, + "low_flap_threshold": 0, + "metadata": { + "name": "curl_timings", + "namespace": "default" + }, + "occurrences": 1, + "occurrences_watermark": 1, + "silenced": [ + "webserver:*" + ], + "output": "sensu-go.curl_timings.time_total 0.005 1552506033\nsensu-go.curl_timings.time_namelookup 0.004", + "output_metric_format": "graphite_plaintext", + "proxy_entity_name": "", + "publish": true, + "round_robin": false, + "runtime_assets": [], + "state": "passing", + "status": 0, + "stdin": false, + "subdue": null, + "subscriptions": [ + "entity:sensu-go-testing" + ], + "timeout": 0, + "total_state_change": 0, + "ttl": 0 + }, + "entity": { + "deregister": false, + "deregistration": {}, + "entity_class": "agent", + "last_seen": 1552495139, + "metadata": { + "name": "sensu-go-testing", + "namespace": "default" + }, + "redact": [ + "password", + "passwd", + "pass", + "api_key", + "api_token", + "access_key", + "secret_key", + "private_key", + "secret" + ], + "subscriptions": [ + "entity:sensu-go-testing" + ], + "system": { + "arch": "amd64", + "hostname": "sensu-go-testing", + "network": { + "interfaces": [ + { + "addresses": [ + "127.0.0.1/8", + "::1/128" + ], + "name": "lo" + }, + { + "addresses": [ + "10.0.2.15/24", + "fe80::5a94:f67a:1bfc:a579/64" + ], + "mac": "08:00:27:8b:c9:3f", + "name": "eth0" + } + ] + }, + "os": "linux", + "platform": "centos", + "platform_family": "rhel", + "platform_version": "7.5.1804", + "processes": null + }, + "user": "agent" + }, + "metrics": { + "points": [ + { + "name": "sensu-go.curl_timings.time_total", + "tags": [], + "timestamp": 1552506033, + "value": 0.005 + }, + { + "name": "sensu-go.curl_timings.time_namelookup", + "tags": [], + "timestamp": 1552506033, + "value": 0.004 + } + ] + }, + "pipelines": [ + { + "type": "Pipeline", + "api_version": "core/v2", + "name": "status_and_metrics_pipeline" + } + ], + "timestamp": 1552506033, + "id": "431a0085-96da-4521-863f-c38b480701e9", + "sequence": 1 + } +} +{{< /code >}} +{{< /language-toggle >}} + +type | +-------------|------ +description | Top-level attribute that specifies the [`sensuctl create`][8] resource type. Events should always be type `Event`. +required | Required for events in `wrapped-json` or `yaml` format for use with [`sensuctl create`][8]. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +type: Event +{{< /code >}} +{{< code json >}} +{ + "type": "Event" +} +{{< /code >}} +{{< /language-toggle >}} + +### Metadata attributes + +| created_by | | +-------------|------ +description | Username of the Sensu user who created the event or last updated the event. Sensu automatically populates the `created_by` field when the event is created or updated. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +created_by: "admin" +{{< /code >}} +{{< code json >}} +{ + "created_by": "admin" +} +{{< /code >}} +{{< /language-toggle >}} + +| namespace | | +-------------|------ +description | [Sensu RBAC namespace][26] that the event belongs to. +required | false +type | String +default | `default` +example | {{< language-toggle >}} +{{< code yml >}} +namespace: production +{{< /code >}} +{{< code json >}} +{ + "namespace": "production" +} +{{< /code >}} +{{< /language-toggle >}} + +### Pipelines attributes + +api_version | +-------------|------ +description | The Sensu API group and version for the [pipeline][44]. Sensu automatically populates the pipelines api_version field when the event is created or updated. For pipelines in this version of Sensu, the api_version is `core/v2`. +required | false +type | String +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +api_version: core/v2 +{{< /code >}} +{{< code json >}} +{ + "api_version": "core/v2" +} +{{< /code >}} +{{< /language-toggle >}} + +name | +-------------|------ +description | Name of the Sensu [pipeline][44] used to process the observability event. Sensu automatically populates the pipeline name field when the event is created or updated. +required | false +type | String +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +name: is_incident +{{< /code >}} +{{< code json >}} +{ + "name": "is_incident" +} +{{< /code >}} +{{< /language-toggle >}} + +type | +-------------|------ +description | The [`sensuctl create`][8] resource type for the [pipeline][44]. Sensu automatically populates the pipelines type field when the event is created or updated. Pipeline resources are always type `Pipeline`. +required | false +type | String +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +type: Pipeline +{{< /code >}} +{{< code json >}} +{ + "type": "Pipeline" +} +{{< /code >}} +{{< /language-toggle >}} + +### Spec attributes + + + +|check | | +-------------|------ +description | [Check definition][1] used to create the event and information about the status and history of the event. The check scope includes attributes described in the [event specification][21] and the [check specification][20]. +type | Map +required | true +example | {{< language-toggle >}} +{{< code yml >}} +check: + check_hooks: + command: metrics-curl -u "http://localhost" + duration: 0.060790838 + env_vars: + executed: 1552506033 + handlers: [] + high_flap_threshold: 0 + history: + - executed: 1552505833 + status: 0 + - executed: 1552505843 + status: 0 + interval: 10 + is_silenced: true + processed_by: sensu-go-sandbox + issued: 1552506033 + last_ok: 1552506033 + low_flap_threshold: 0 + metadata: + name: curl_timings + namespace: default + occurrences: 1 + occurrences_watermark: 1 + silenced: + - webserver:* + output: sensu-go.curl_timings.time_total 0.005 + output_metric_format: graphite_plaintext + proxy_entity_name: '' + publish: true + round_robin: false + runtime_assets: [] + state: passing + status: 0 + stdin: false + subdue: + subscriptions: + - entity:sensu-go-testing + timeout: 0 + total_state_change: 0 + ttl: 0 +{{< /code >}} +{{< code json >}} +{ + "check": { + "check_hooks": null, + "command": "metrics-curl -u \"http://localhost\"", + "duration": 0.060790838, + "env_vars": null, + "executed": 1552506033, + "handlers": [], + "high_flap_threshold": 0, + "history": [ + { + "executed": 1552505833, + "status": 0 + }, + { + "executed": 1552505843, + "status": 0 + } + ], + "interval": 10, + "is_silenced": true, + "processed_by": "sensu-go-sandbox", + "issued": 1552506033, + "last_ok": 1552506033, + "low_flap_threshold": 0, + "metadata": { + "name": "curl_timings", + "namespace": "default" + }, + "occurrences": 1, + "occurrences_watermark": 1, + "silenced": [ + "webserver:*" + ], + "output": "sensu-go.curl_timings.time_total 0.005", + "output_metric_format": "graphite_plaintext", + "proxy_entity_name": "", + "publish": true, + "round_robin": false, + "runtime_assets": [], + "state": "passing", + "status": 0, + "stdin": false, + "subdue": null, + "subscriptions": [ + "entity:sensu-go-testing" + ], + "timeout": 0, + "total_state_change": 0, + "ttl": 0 + } +} +{{< /code >}} +{{< /language-toggle >}} + +|entity | | +-------------|------ +description | [Entity attributes][2] from the originating entity (agent or proxy).

    For events created with the [core/v2/events API][35], if the event's entity does not already exist, the sensu-backend automatically creates a proxy entity when the event is published. +type | Map +required | true +example | {{< language-toggle >}} +{{< code yml >}} +entity: + deregister: false + deregistration: {} + entity_class: agent + last_seen: 1552495139 + metadata: + name: sensu-go-testing + namespace: default + redact: + - password + - passwd + - pass + - api_key + - api_token + - access_key + - secret_key + - private_key + - secret + subscriptions: + - entity:sensu-go-testing + system: + arch: amd64 + hostname: sensu-go-testing + network: + interfaces: + - addresses: + - 127.0.0.1/8 + - "::1/128" + name: lo + - addresses: + - 10.0.2.15/24 + - fe80::5a94:f67a:1bfc:a579/64 + mac: '08:00:27:8b:c9:3f' + name: eth0 + os: linux + platform: centos + platform_family: rhel + platform_version: 7.5.1804 + user: agent + +{{< /code >}} +{{< code json >}} +{ + "entity": { + "deregister": false, + "deregistration": {}, + "entity_class": "agent", + "last_seen": 1552495139, + "metadata": { + "name": "sensu-go-testing", + "namespace": "default" + }, + "redact": [ + "password", + "passwd", + "pass", + "api_key", + "api_token", + "access_key", + "secret_key", + "private_key", + "secret" + ], + "subscriptions": [ + "entity:sensu-go-testing" + ], + "system": { + "arch": "amd64", + "hostname": "sensu-go-testing", + "network": { + "interfaces": [ + { + "addresses": [ + "127.0.0.1/8", + "::1/128" + ], + "name": "lo" + }, + { + "addresses": [ + "10.0.2.15/24", + "fe80::5a94:f67a:1bfc:a579/64" + ], + "mac": "08:00:27:8b:c9:3f", + "name": "eth0" + } + ] + }, + "os": "linux", + "platform": "centos", + "platform_family": "rhel", + "platform_version": "7.5.1804" + }, + "user": "agent" + } +} +{{< /code >}} +{{< /language-toggle >}} + +id | | +-------------|------ +description | Universally unique identifier (UUID) for the event. Logged as `event_id`.

    Sensu automatically populates the `id` value for the event. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +id: 431a0085-96da-4521-863f-c38b480701e9 +{{< /code >}} +{{< code json >}} +{ + "id": "431a0085-96da-4521-863f-c38b480701e9" +} +{{< /code >}} +{{< /language-toggle >}} + + + +|metrics | | +-------------|------ +description | Metrics collected by the entity in Sensu metric format. Review the [metrics attributes][30]. +type | Map +required | false +example | {{< language-toggle >}} +{{< code yml >}} +metrics: + points: + - name: sensu-go.curl_timings.time_total + tags: [] + timestamp: 1552506033 + value: 0.005 + - name: sensu-go.curl_timings.time_namelookup + tags: [] + timestamp: 1552506033 + value: 0.004 +{{< /code >}} +{{< code json >}} +{ + "metrics": { + "points": [ + { + "name": "sensu-go.curl_timings.time_total", + "tags": [], + "timestamp": 1552506033, + "value": 0.005 + }, + { + "name": "sensu-go.curl_timings.time_namelookup", + "tags": [], + "timestamp": 1552506033, + "value": 0.004 + } + ] + } +} +{{< /code >}} +{{< /language-toggle >}} + + + +sequence | | +-------------|------ +description | Event sequence number. The Sensu agent sets the sequence to 1 at startup, then increments the sequence by 1 for every successive check execution or keepalive event. If the agent restarts or reconnects to another backend, the sequence value resets to 1.

    A sequence value of 0 indicates that an outdated or non-conforming agent generated the event.

    Sensu only increments the sequence for agent-executed events. Sensu does not update the sequence for events created with the [core/v2/events API][35]. +required | false +type | Integer +example | {{< language-toggle >}} +{{< code yml >}} +sequence: 1 +{{< /code >}} +{{< code json >}} +{ + "sequence": 1 +} +{{< /code >}} +{{< /language-toggle >}} + +|timestamp | | +-------------|------ +description | Time that the event occurred. In seconds since the Unix epoch.

    Sensu automatically populates the timestamp value for the event. For events created with the [core/v2/events API][35], you can specify a `timestamp` value in the request body. +required | false +type | Integer +default | Time that the event occurred +example | {{< language-toggle >}} +{{< code yml >}} +timestamp: 1522099512 +{{< /code >}} +{{< code json >}} +{ + "timestamp": 1522099512 +} +{{< /code >}} +{{< /language-toggle >}} + +### Check attributes + +Sensu events include a `check` scope that contains information about how the event was created, including any attributes defined in the [check specification][20], and information about the event and its history, including the attributes defined below. + +duration | | +-------------|------ +description | Command execution time. In seconds. +required | false +type | Float +example | {{< language-toggle >}} +{{< code yml >}} +duration: 1.903135228 +{{< /code >}} +{{< code json >}} +{ + "duration": 1.903135228 +} +{{< /code >}} +{{< /language-toggle >}} + +executed | | +-------------|------ +description | Time at which the check request was executed. In seconds since the Unix epoch.

    The difference between a request's `issued` and `executed` values is the request latency.

    For agent-executed checks, Sensu automatically populates the `executed` value. For events created with the [core/v2/events API][35], the default `executed` value is `0` unless you specify a value in the request body. +required | false +type | Integer +example | {{< language-toggle >}} +{{< code yml >}} +executed: 1522100915 +{{< /code >}} +{{< code json >}} +{ + "executed": 1522100915 +} +{{< /code >}} +{{< /language-toggle >}} + +history | | +-------------|------ +description | Check status history for the last 21 check executions. Read [history attributes][32].

    Sensu automatically populates the history attributes with check execution data.

    To store more than the last 21 check executions, use one of our [long-term event storage integrations][41]. +required | false +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +history: +- executed: 1552505983 + status: 0 +- executed: 1552505993 + status: 0 +{{< /code >}} +{{< code json >}} +{ + "history": [ + { + "executed": 1552505983, + "status": 0 + }, + { + "executed": 1552505993, + "status": 0 + } + ] +} +{{< /code >}} +{{< /language-toggle >}} + +is_silenced | | +-------------|------ +description | If `true`, the event was silenced at the time of processing. Otherwise, `false`. If `true`, the event. Check definitions also list the silenced entries that match the event in the `silenced` array. +required | false +type | Boolean +example | {{< language-toggle >}} +{{< code yml >}} +is_silenced: true +{{< /code >}} +{{< code json >}} +{ + "is_silenced": "true" +} +{{< /code >}} +{{< /language-toggle >}} + + + +issued | | +-------------|------ +description | Time that the check request was issued. In seconds since the Unix epoch.

    The difference between a request's `issued` and `executed` values is the request latency.

    For agent-executed checks, Sensu automatically populates the `issued` value. For events created with the [core/v2/events API][35], the default `issued` value is `0` unless you specify a value in the request body. +required | false +type | Integer +example | {{< language-toggle >}} +{{< code yml >}} +issued: 1552506033 +{{< /code >}} +{{< code json >}} +{ + "issued": 1552506033 +} +{{< /code >}} +{{< /language-toggle >}} + +last_ok | | +-------------|------ +description | Last time that the check returned an OK status (`0`). In seconds since the Unix epoch.

    For agent-executed checks, Sensu automatically populates the `last_ok` value. For events created with the [core/v2/events API][35], the `last_ok` attribute will default to `0` even if you specify OK status in the request body. +required | false +type | Integer +example | {{< language-toggle >}} +{{< code yml >}} +last_ok: 1552506033 +{{< /code >}} +{{< code json >}} +{ + "last_ok": 1552506033 +} +{{< /code >}} +{{< /language-toggle >}} + +occurrences | | +-------------|------ +description | Number of preceding events with the same status as the current event (OK, WARNING, CRITICAL, or UNKNOWN). Starting at `1`, the `occurrences` attribute increments for events with the same status as the preceding event and resets whenever the status changes. Read [Use event data][31] for more information.

    Sensu automatically populates the `occurrences` value. For events created with the [core/v2/events API][35], Sensu overwrites any `occurences` value you specify in the request body with the correct value. +required | false +type | Integer greater than 0 +example | {{< language-toggle >}} +{{< code yml >}} +occurrences: 1 +{{< /code >}} +{{< code json >}} +{ + "occurrences": 1 +} +{{< /code >}} +{{< /language-toggle >}} + +occurrences_watermark | | +-------------|------ +description | For incident and resolution events, the number of preceding events with an OK status (for incident events) or non-OK status (for resolution events). The `occurrences_watermark` attribute gives you useful information when looking at events that change status between OK (`0`)and non-OK (`1`-WARNING, `2`-CRITICAL, or UNKNOWN).

    Sensu resets `occurrences_watermark` to `1` whenever an event for a given entity and check transitions between OK and non-OK. Within a sequence of only OK or only non-OK events, Sensu increments `occurrences_watermark` only when the `occurrences` attribute is greater than the preceding `occurrences_watermark`. Read [Use event data][31] for more information.

    Sensu automatically populates the `occurrences_watermark` value. For events created with the [core/v2/events API][35], Sensu overwrites any `occurences_watermark` value you specify in the request body with the correct value. +required | false +type | Integer greater than 0 +example | {{< language-toggle >}} +{{< code yml >}} +occurrences_watermark: 1 +{{< /code >}} +{{< code json >}} +{ + "occurrences_watermark": 1 +} +{{< /code >}} +{{< /language-toggle >}} + +output | | +-------------|------ +description | Output from the execution of the check command. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +output: "sensu-go.curl_timings.time_total 0.005 +{{< /code >}} +{{< code json >}} +{ + "output": "sensu-go.curl_timings.time_total 0.005" +} +{{< /code >}} +{{< /language-toggle >}} + + + +processed_by | | +-------------|------ +description | The name of the agent that processed the event. Useful for determining which agent processed an event executed by a [proxy check request][42] or a [POST request to the events API][43]. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +processed_by: sensu-go-sandbox +{{< /code >}} +{{< code json >}} +{ + "processed_by": "sensu-go-sandbox" +} +{{< /code >}} +{{< /language-toggle >}} + + + +silenced | | +-------------|------ +description | Array of silencing entries that match the event. The `silenced` attribute is only present for events if one or more silencing entries matched the event at time of processing. If the `silenced` attribute is not present in an event, the event was not silenced at the time of processing. +required | false +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +silenced: +- webserver:* +{{< /code >}} +{{< code json >}} +{ + "silenced": [ + "webserver:*" + ] +} +{{< /code >}} +{{< /language-toggle >}} + +state | | +-------------|------ +description | State of the check: `passing` (status `0`), `failing` (status other than `0`), or `flapping`. Use the `low_flap_threshold` and `high_flap_threshold` [check attributes][33] to configure `flapping` state detection.

    Sensu automatically populates the `state` based on the `status`. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +state: passing +{{< /code >}} +{{< code json >}} +{ + "state": "passing" +} +{{< /code >}} +{{< /language-toggle >}} + + + +status | | +-------------|------ +description | Exit status code produced by the check.
    • `0` indicates OK
    • `1` indicates WARNING
    • `2` indicates CRITICAL
    Exit status codes other than `0`, `1`, or `2` indicate an UNKNOWN or custom status.

    For agent-executed checks, Sensu automatically populates the `status` value based on the check result. For events created with the [core/v2/events API][35], Sensu assumes the status is `0` (OK) unless you specify a non-zero value in the request body. +required | false +type | Integer +example | {{< language-toggle >}} +{{< code yml >}} +status: 0 +{{< /code >}} +{{< code json >}} +{ + "status": 0 +} +{{< /code >}} +{{< /language-toggle >}} + +total_state_change | | +-------------|------ +description | Total state change percentage for the check's history.

    For agent-executed checks, Sensu automatically populates the `total_state_change` value. For events created with the [core/v2/events API][35], the `total_state_change` attribute will default to `0` even if you specify a different value or change the `status` value in the request body. +required | false +type | Integer +example | {{< language-toggle >}} +{{< code yml >}} +total_state_change: 0 +{{< /code >}} +{{< code json >}} +{ + "total_state_change": 0 +} +{{< /code >}} +{{< /language-toggle >}} + +#### History attributes + +executed | | +-------------|------ +description | Time at which the check request was executed. In seconds since the Unix epoch.

    Sensu automatically populates the `executed` value with check execution data. For events created with the [core/v2/events API][35], the `executed` default value is `0`. +required | false +type | Integer +example | {{< language-toggle >}} +{{< code yml >}} +executed: 1522100915 +{{< /code >}} +{{< code json >}} +{ + "executed": 1522100915 +} +{{< /code >}} +{{< /language-toggle >}} + +status | | +-------------|------ +description | Exit status code produced by the check.
    • `0` indicates OK
    • `1` indicates WARNING
    • `2` indicates CRITICAL
    Exit status codes other than `0`, `1`, or `2` indicate an UNKNOWN or custom status.

    Sensu automatically populates the `status` value with check execution data. +required | false +type | Integer +example | {{< language-toggle >}} +{{< code yml >}} +status: 0 +{{< /code >}} +{{< code json >}} +{ + "status": 0 +} +{{< /code >}} +{{< /language-toggle >}} + +### Metrics attributes + +handlers | | +-------------|------ +description | Array of Sensu handlers to use for events created by the check. Each array item must be a string. +required | false +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +handlers: +- influx-db +{{< /code >}} +{{< code json >}} +{ + "handlers": [ + "influx-db" + ] +} +{{< /code >}} +{{< /language-toggle >}} + + + +points | | +-------------|------ +description | Metrics data points, including a name, timestamp, value, and tags. Read [points attributes][34]. +required | false +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +points: +- name: sensu-go.curl_timings.time_total + tags: + - name: response_time_in_ms + value: '101' + timestamp: 1552506033 + value: 0.005 +- name: sensu-go.curl_timings.time_namelookup + tags: + - name: namelookup_time_in_ms + value: '57' + timestamp: 1552506033 + value: 0.004 +{{< /code >}} +{{< code json >}} +{ + "points": [ + { + "name": "sensu-go.curl_timings.time_total", + "tags": [ + { + "name": "response_time_in_ms", + "value": "101" + } + ], + "timestamp": 1552506033, + "value": 0.005 + }, + { + "name": "sensu-go.curl_timings.time_namelookup", + "tags": [ + { + "name": "namelookup_time_in_ms", + "value": "57" + } + ], + "timestamp": 1552506033, + "value": 0.004 + } + ] +} +{{< /code >}} +{{< /language-toggle >}} + +#### Points attributes + +name | | +-------------|------ +description | Metric name in the format `$entity.$check.$metric` where `$entity` is the entity name, `$check` is the check name, and `$metric` is the metric name. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +name: sensu-go.curl_timings.time_total +{{< /code >}} +{{< code json >}} +{ + "name": "sensu-go.curl_timings.time_total" +} +{{< /code >}} +{{< /language-toggle >}} + +tags | | +-------------|------ +description | Optional tags to include with the metric. Each element of the array must be a hash that contains two key-value pairs: the `name` of the tag and the `value`. Both values of the pairs must be strings. +required | false +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +tags: +- name: response_time_in_ms + value: '101' +{{< /code >}} +{{< code json >}} +{ + "tags": [ + { + "name": "response_time_in_ms", + "value": "101" + } + ] +} +{{< /code >}} +{{< /language-toggle >}} + +timestamp | | +-------------|------ +description | Time at which the metric was collected. In seconds since the Unix epoch. Sensu automatically populates the timestamp values for metrics data points. +required | false +type | Integer +example | {{< language-toggle >}} +{{< code yml >}} +timestamp: 1552506033 +{{< /code >}} +{{< code json >}} +{ + "timestamp": 1552506033 +} +{{< /code >}} +{{< /language-toggle >}} + +value | | +-------------|------ +description | Metric value. +required | false +type | Float +example | {{< language-toggle >}} +{{< code yml >}} +value: 0.005 +{{< /code >}} +{{< code json >}} +{ + "value": 0.005 +} +{{< /code >}} +{{< /language-toggle >}} + + +[1]: ../../observe-schedule/checks/ +[2]: ../../observe-entities/entities#entities-specification +[3]: ../../observe-entities/entities/ +[4]: ../#status-only-events +[5]: ../#metrics-only-events +[6]: ../../observe-schedule/collect-metrics-with-checks/ +[7]: ../../observe-schedule/checks/#check-specification +[8]: ../../../sensuctl/create-manage-resources/#create-resources +[9]: #spec-attributes +[10]: ../../observe-schedule/agent#create-observability-events-using-service-checks +[11]: ../../observe-schedule/agent#create-observability-events-using-the-agent-api +[12]: ../../observe-schedule/agent#create-observability-events-using-the-agent-tcp-and-udp-sockets +[13]: ../../observe-schedule/agent#create-observability-events-using-the-statsd-listener +[14]: ../../../api/core/events/#eventsentitycheck-put +[15]: ../../../web-ui/ +[16]: ../../../api/core/events/ +[17]: ../../../sensuctl/ +[18]: ../../../sensuctl/#preferred-output-format +[19]: ../#status-and-metrics-events +[20]: ../../observe-schedule/checks#check-specification +[21]: #check-attributes +[22]: #metrics-attributes +[23]: ../../observe-filter/reduce-alert-fatigue/ +[24]: ../../observe-filter/filters/ +[25]: ../../observe-schedule/checks/#check-result-specification +[26]: ../../../operations/control-access/namespaces/ +[27]: ../../observe-filter/filters/#filter-for-state-change-only +[28]: ../../observe-filter/filters/#filter-for-repeated-events +[29]: #metadata-attributes +[30]: #metrics-attributes +[31]: #use-event-data +[32]: #history-attributes +[33]: ../../observe-schedule/checks#spec-attributes +[34]: #points-attributes +[35]: ../../../api/core/events/#create-a-new-event +[36]: #state-attribute +[37]: ../../observe-schedule/checks/#high-flap-threshold +[38]: https://assets.nagios.com/downloads/nagioscore/docs/nagioscore/3/en/flapping.html +[39]: #flap-detection-algorithm +[40]: ../../observe-filter/filters/#check-attributes-available-to-filters +[41]: ../../../plugins/featured-integrations/#time-series-and-long-term-event-storage +[42]: ../../observe-schedule/checks/#proxy-checks +[43]: ../../observe-schedule/agent/#create-observability-events-using-the-agent-api +[44]: ../../observe-process/pipelines/ +[45]: #pipelines-attributes +[46]: ../../../operations/maintain-sensu/troubleshoot/#use-a-debug-handler +[47]: ../../observe-schedule/checks/#low-flap-threshold diff --git a/content/sensu-go/6.12/observability-pipeline/observe-filter/_index.md b/content/sensu-go/6.12/observability-pipeline/observe-filter/_index.md new file mode 100644 index 0000000000..db5b3298ef --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-filter/_index.md @@ -0,0 +1,83 @@ +--- +title: "Filter your observation data" +linkTitle: "Filter" +description: "Learn how Sensu event filters apply your specified conditions, triggers, and thresholds to give you control over which observability events are processed." +product: "Sensu Go" +version: "6.12" +weight: 50 +layout: "single" +toc: false +menu: + sensu-go-6.12: + parent: observability-pipeline + identifier: observe-filter +--- + + + + +** or click any element in the pipeline to jump to it.** + +**In the filter stage, Sensu executes [event filters][1]**. + +The filter stage of the Sensu observability pipeline applies the conditions, triggers, and thresholds you specify in your [event filter][1] defintions to the events your checks generate. +Event filters give you control over which events continue through your pipeline and become alerts. +For example, use the [built-in is_incident event filter][7] to allow only high-priority events through your Sensu pipeline and reduce noise for operators. + +To tell Sensu which event filters you want to apply, you list them in your [pipeline][2] definitions. +Sensu compares your observation data in events against the [expressions][6] in your event filters to determine whether each event should continue through the pipeline or be removed. +Event filters can be [inclusive or exclusive][4], so you can require events to match or not match your filter expressions. + +Here's an example that shows the resource definition for an event filter that would allow handling for only events with the custom entity label `"region": "us-west-1"`: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: EventFilter +api_version: core/v2 +metadata: + name: production_filter +spec: + action: allow + expressions: + - event.entity.labels['region'] == 'us-west-1' +{{< /code >}} + +{{< code json >}} +{ + "type": "EventFilter", + "api_version": "core/v2", + "metadata": { + "name": "production_filter" + }, + "spec": { + "action": "allow", + "expressions": [ + "event.entity.labels['region'] == 'us-west-1'" + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +Sensu applies event filters in the order that they are listed in your pipeline definition. +Any events that the filters do not remove from your pipeline will be [processed][3] according to your handler configuration. + +As soon as an event filter removes an event from your pipeline because it does not meet the conditions, triggers, or thresholds you specified, the Sensu observability pipeline ceases analysis for the event. +Sensu will not [transform][5] or [process][3] events that your event filter removes from your pipeline. + +Use [Bonsai][8], the Sensu asset hub, to discover, download, and share Sensu event filter dynamic runtime assets. +Read [Use assets to install plugins][9] to get started. + + +[1]: filters/ +[2]: ../observe-process/pipelines/ +[3]: ../observe-process/ +[4]: filters/#inclusive-and-exclusive-event-filters +[5]: ../observe-transform/ +[6]: ../observe-filter/filters#filter-expression-comparison +[7]: filters/#built-in-filter-is_incident +[8]: https://bonsai.sensu.io/ +[9]: ../../plugins/use-assets-to-install-plugins/ diff --git a/content/sensu-go/6.12/observability-pipeline/observe-filter/filters.md b/content/sensu-go/6.12/observability-pipeline/observe-filter/filters.md new file mode 100644 index 0000000000..ec3d4ec208 --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-filter/filters.md @@ -0,0 +1,1331 @@ +--- +title: "Event filters reference" +linkTitle: "Event Filters Reference" +reference_title: "Event filters" +type: "reference" +description: "Read this reference to use Sensu's built-in event filters (or create your own) to control which events Sensu handlers will take action on." +weight: 20 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: observe-filter +--- + +Sensu executes event filters during the **[filter][45]** stage of the [observability pipeline][44]. + +Sensu event filters are applied when you configure a [pipeline][49] with a workflow that uses one or more filters. +Before executing the handler in a pipeline workflow, the Sensu backend will apply any event filters listed in the same pipeline workflow to the observation data in events. +If the filters do not remove the event, the handler will be executed. + +The event filter analysis performs these steps: + +* When the Sensu backend is processing an event, it checks for filters in the pipeline (or pipelines) specified in the event's check definition. +Before executing any handlers listed in the pipeline, Sensu applies any event filters and mutators listed in the pipeline. +* If multiple filters are configured for a pipeline, they are executed sequentially. +* Filter `expressions` are compared with event data. + +Event filters can be inclusive (only matching events are handled) or exclusive (matching events are not handled). +Read [Inclusive and exclusive event filters][1] for details. + +As soon as a filter removes an event, no further analysis is performed and the pipeline workflow's handler will not be executed. + +## Event filter example (minimum required attributes) + +This example shows the minimum required attributes for an event filter resource: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: EventFilter +api_version: core/v2 +metadata: + name: filter_minimum +spec: + action: allow + expressions: + - event.check.occurrences == 1 +{{< /code >}} + +{{< code json >}} +{ + "type": "EventFilter", + "api_version": "core/v2", + "metadata": { + "name": "filter_minimum" + }, + "spec": { + "action": "allow", + "expressions": [ + "event.check.occurrences == 1" + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Inclusive and exclusive event filters + +Event filters can be *inclusive* or *exclusive*: + +- In *inclusive* filtering, only events that match the defined filter expressions will be handled. +- In *exclusive* filtering, events will be handled only if they do not match the defined filter expressions. + +Use the [`action` attribute][34] in the event filter definition to control whether the filter is inclusive or exclusive: + +- To use inclusive filtering, set the `action` attribute to `allow` in the event filter definition (`"action": "allow"`). +- To use exclusive filtering, set the `action` attribute to `deny` in the event filter definition (`"action": "deny"`). + +### Multiple inclusive or exclusive event filters + +Multiple *inclusive* event filters are equivalent to using an `AND` query operator: Sensu will only handle events if they match *all* of the inclusive filters (`x AND y AND z`). + +Multiple *exclusive* event filters are equivalent to using an `OR` operator: Sensu will only handle events if they *don’t* match *any* of the exclusive filters (`x OR y OR z`). + +## Filter expression comparison + +Event filter expressions are compared directly with their event data counterparts. + +- For *inclusive* event filter definitions (`"action": "allow"`), matching expressions will result in the filter returning a `true` value. The event will pass through the filter and continue to be processed with additional filters (if defined), mutators (if defined), and handlers. +- For *exclusive* event filter definitions (`"action": "deny"`), matching expressions will result in the filter returning a `false` value, and the event will not pass through the filter. + +## Filter expression evaluation + +When more complex conditional logic is needed than direct filter expression comparison, Sensu event filters provide support for expression evaluation using [Otto][31]. +Otto is an ECMAScript 5 (JavaScript) virtual machine that evaluates JavaScript expressions provided in an event filter. + +In event filter expressions, place string values inside single or double quotes. +These filter expressions are equivalent in EMCAScript: + +{{< code text >}} +event.check.annotations['service_priority'] == 1 +event.check.annotations["service_priority"] == 1 +{{< /code >}} + +There are some caveats to using Otto: not all of the regular expressions (regex) specified in ECMAScript 5 will work. +Review the [Otto README][32] for more details. + +Use [Go regex syntax][3] to create event filter expressions that combine any available [event][46], [check][47], or [entity][48] attributes with `match()`. +For example, this event filter allows handling for events whose `event.check.name` ends with `metrics`: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: EventFilter +api_version: core/v2 +metadata: + name: metrics-checks-only +spec: + action: allow + expressions: + - event.check.name.match(/metrics$/) +{{< /code >}} + +{{< code json >}} +{ + "type": "EventFilter", + "api_version": "core/v2", + "metadata": { + "name": "metrics-checks-only" + }, + "spec": { + "action": "allow", + "expressions": [ + "event.check.name.match(/metrics$/)" + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +Here's another example that uses regex matching for event entity labels. +This event filter allows handling for events created by entities with the `region` label `us-west-1`, `us-west-2`, or `us-west-3`: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: EventFilter +api_version: core/v2 +metadata: + name: us-west-events +spec: + action: allow + expressions: + - event.entity.labels.region.match(/us-west-\b[1-3]\b/) +{{< /code >}} + +{{< code json >}} +{ + "type": "EventFilter", + "api_version": "core/v2", + "metadata": { + "name": "us-west-events" + }, + "spec": { + "action": "allow", + "expressions": [ + "event.entity.labels.region.match(/us-west-\b[1-3]\b/)" + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Filter dynamic runtime assets + +Sensu event filters can include dynamic runtime assets in their execution context. +When valid dynamic runtime assets are associated with an event filter, Sensu evaluates any files it finds that have a `.js` extension before executing the filter. +The result of evaluating the scripts is cached for a given asset set for the sake of performance. +For an example of how to implement an event filter as an asset, read [Reduce alert fatigue][30]. + +## Built-in event filters + +Sensu includes built-in event filters to help you customize event pipelines for metrics and alerts. +To start using built-in event filters, read [Send Slack alerts][4] and [Plan maintenance][5]. + +{{% notice note %}} +**NOTE**: Sensu Go does not include the built-in occurrence-based event filter in Sensu Core 1.x, but you can replicate its functionality with the [repeated events filter definition](#filter-for-repeated-events). +{{% /notice %}} + +### Built-in filter: is_incident + +The is_incident event filter is included in every installation of the [Sensu backend][8]. +You can use the is_incident filter to allow only high-priority events through a Sensu pipeline. +For example, you can use the is_incident filter to reduce noise when sending notifications to Slack. +When applied to a pipeline workflow, the is_incident filter allows warning (`"status": 1`), critical (`"status": 2`), other (unknown or custom status), and resolution events to be processed. + +To use the is_incident event filter, include `is_incident` in the pipeline [`filters` object][50]: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Pipeline +api_version: core/v2 +metadata: + name: incident_alerts +spec: + workflows: + - name: slack_alerts + filters: + - name: is_incident + type: EventFilter + api_version: core/v2 + handler: + name: slack + type: Handler + api_version: core/v2 +{{< /code >}} + +{{< code json >}} +{ + "type": "Pipeline", + "api_version": "core/v2", + "metadata": { + "name": "incident_alerts" + }, + "spec": { + "workflows": [ + { + "name": "slack_alerts", + "filters": [ + { + "name": "is_incident", + "type": "EventFilter", + "api_version": "core/v2" + } + ], + "handler": { + "name": "slack", + "type": "Handler", + "api_version": "core/v2" + } + } + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +The is_incident event filter applies the following filtering logic: + +| status | allow | discard | | | | | +| ----- | ----- | ------- | --- | --- | --- | --- | +| 0 | | {{< cross >}} | | | | | +| 1 | {{< check >}} | | | | | | +| 2 | {{< check >}} | | | | | | +| other (unknown or custom status) | {{< check >}} | | | | | | +| resolution event
    such as 1 --> 0
    or 3 --> 0 | {{< check >}} | | | | | | + +### Built-in filter: not_silenced + +[Sensu silencing][6] lets you suppress handler execution on an on-demand basis so you can quiet incoming alerts and [plan maintenance][5]. + +To allow silencing for a pipeline workflow, add `not_silenced` to the pipeline [`filters` object][50]: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Pipeline +api_version: core/v2 +metadata: + name: incident_alerts +spec: + workflows: + - name: slack_alerts + filters: + - name: is_incident + type: EventFilter + api_version: core/v2 + - name: not_silenced + type: EventFilter + api_version: core/v2 + handler: + name: slack + type: Handler + api_version: core/v2 +{{< /code >}} + +{{< code json >}} +{ + "type": "Pipeline", + "api_version": "core/v2", + "metadata": { + "name": "incident_alerts" + }, + "spec": { + "workflows": [ + { + "name": "slack_alerts", + "filters": [ + { + "name": "is_incident", + "type": "EventFilter", + "api_version": "core/v2" + }, + { + "name": "not_silenced", + "type": "EventFilter", + "api_version": "core/v2" + } + ], + "handler": { + "name": "slack", + "type": "Handler", + "api_version": "core/v2" + } + } + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +When applied in a pipeline configuration, the not_silenced event filter silences events that include the `silenced` attribute. +The pipeline in the example above uses both the not_silenced and [is_incident][7] event filters, preventing low-priority and silenced events from being sent to Slack. + +### Built-in filter: has_metrics + +The has_metrics event filter is included in every installation of the [Sensu backend][8]. +When applied in a pipeline workflow, the has_metrics filter allows only events that contain [Sensu metrics][9] to be processed. +You can use the has_metrics filter to prevent handlers that require metrics from failing in case of an error in metric collection. + +To use the has_metrics event filter, include `has_metrics` in the pipeline `filters` array: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Pipeline +api_version: core/v2 +metadata: + name: metrics_pipeline +spec: + workflows: + - name: influxdb_metrics + filters: + - name: has_metrics + type: EventFilter + api_version: core/v2 + handler: + name: influxdb + type: Handler + api_version: core/v2 +{{< /code >}} + +{{< code json >}} +{ + "type": "Pipeline", + "api_version": "core/v2", + "metadata": { + "name": "metrics_pipeline" + }, + "spec": { + "workflows": [ + { + "name": "influxdb_metrics", + "filters": [ + { + "name": "has_metrics", + "type": "EventFilter", + "api_version": "core/v2" + } + ], + "handler": { + "name": "influxdb", + "type": "Handler", + "api_version": "core/v2" + } + } + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +When applied in a pipeline configuration, the has_metrics event filter allows only events that include a [`metrics` scope][9]. + +## Build event filter expressions with Sensu query expressions + +You can write custom event filter expressions as [Sensu query expressions][27] using the event data attributes described in this section. +For more information about event attributes, read the [event reference][28]. + +### Syntax quick reference + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    operatordescription
    === / !==Identity operator / Nonidentity operator
    == / !=Equality operator / Inequality operator
    && / ||Logical AND / Logical OR
    < / >Less than / Greater than
    <= / >=Less than or equal to / Greater than or equal to
    + +### Event attributes available to filters + +| attribute | type | description | +| ------------------- | ------- | ----------- | +`event.has_check` | Boolean | Returns true if the event contains check data +`event.has_metrics` | Boolean | Returns true if the event contains metrics +`event.is_incident` | Boolean | Returns true for critical alerts (status `2`), warnings (status `1`), and resolution events (status `0` transitioning from status `1` or `2`) +`event.is_resolution` | Boolean | Returns true if the event status is OK (`0`) and the previous event was of a non-zero status +`event.is_silenced` | Boolean | Returns true if the event matches an active silencing entry +`event.timestamp` | integer | Time that the event occurred in seconds since the Unix epoch + +### Check attributes available to filters + +| attribute | type | description | +| ---------------------------------- | ------- | ----------- | +`event.check.annotations` | map | Custom [annotations][19] applied to the check +`event.check.command` | string | The command executed by the check +`event.check.cron` | string | [Check execution schedule][21] using cron syntax +`event.check.discard_output` | Boolean | Whether the check is configured to discard check output from event data +`event.check.duration` | float | Command execution time in seconds +`event.check.env_vars` | array | Environment variables used with command execution +`event.check.executed` | integer | Time that the check was executed in seconds since the Unix epoch +`event.check.handlers` | array | Sensu event [handlers][22] assigned to the check +`event.check.high_flap_threshold` | integer | The check's flap detection high threshold in percent state change +`event.check.history` | array | [Check status history][20] for the last 21 check executions +`event.check.hooks` | array | [Check hook][12] execution data +`event.check.interval` | integer | The check execution frequency in seconds +`event.check.issued` | integer | Time that the check request was issued in seconds since the Unix epoch +`event.check.labels` | map | Custom [labels][19] applied to the check +`event.check.last_ok` | integer | The last time that the check returned an OK status (`0`) in seconds since the Unix epoch +`event.check.low_flap_threshold` | integer | The check's flap detection low threshold in percent state change +`event.check.max_output_size` | integer | Maximum size of stored check outputs in bytes +`event.check.name` | string | Check name +`event.check.occurrences` | integer | The [number of preceding events][29] with the same status as the current event +`event.check.occurrences_watermark` | integer | For resolution events, the [number of preceding events][29] with a non-OK status +`event.check.output` | string | The output from the execution of the check command +`event.check.output_metric_format` | string | The [metric format][13] generated by the check command: `nagios_perfdata`, `graphite_plaintext`, `influxdb_line`, `opentsdb_line`, or `prometheus_text` +`event.check.output_metric_handlers` | array | Sensu metric [handlers][22] assigned to the check +`event.check.proxy_entity_name` | string | The entity name, used to create a [proxy entity][14] for an external resource +`event.check.proxy_requests` | map | [Proxy request][15] configuration +`event.check.publish` | Boolean | Whether the check is scheduled automatically +`event.check.round_robin` | Boolean | Whether the check is configured to be executed in a [round-robin style][16] +`event.check.runtime_assets` | array | Sensu [dynamic runtime assets][17] used by the check +`event.check.state` | string | The state of the check: `passing` (status `0`), `failing` (status other than `0`), or `flapping` +`event.check.status` | integer | Exit status code produced by the check: `0` (OK), `1` (warning), `2` (critical), or other status (unknown or custom status) +`event.check.stdin` | Boolean | Whether the Sensu agent writes JSON-serialized entity and check data to the command process’ stdin +`event.check.subscriptions` | array | Subscriptions that the check belongs to +`event.check.timeout` | integer | The check execution duration timeout in seconds +`event.check.total_state_change` | integer | The total state change percentage for the check’s history +`event.check.ttl` | integer | The time-to-live (TTL) until the event is considered stale, in seconds +`event.metrics.handlers` | array | Sensu metric [handlers][22] assigned to the check +`event.metrics.points` | array | [Metrics data points][23] including a name, timestamp, value, and tags + +### Entity attributes available to filters + +| attribute | type | description | +| ------------------------------------ | ------- | ----------- | +`event.entity.annotations` | map | Custom [annotations][24] assigned to the entity +`event.entity.deregister` | Boolean | Whether the agent entity should be removed when it stops sending [keepalive messages][26] +`event.entity.deregistration` | map | A map that contains a handler name for use when an entity is deregistered +`event.entity.entity_class` | string | The entity type: usually `agent` or `proxy` +`event.entity.labels` | map | Custom [labels][24] assigned to the entity +`event.entity.last_seen` | integer | Timestamp the entity was last seen in seconds since the Unix epoch +`event.entity.name` | string | Entity name +`event.entity.redact` | array | List of items to redact from log messages +`event.entity.subscriptions` | array | List of subscriptions assigned to the entity +`event.entity.system` | map | Information about the [entity's system][18] +`event.entity.system.arch` | string | The entity's system architecture +`event.entity.system.hostname` | string | The entity's hostname +`event.entity.system.network` | map | The entity's network interface list +`event.entity.system.os` | string | The entity’s operating system +`event.entity.system.platform` | string | The entity’s operating system distribution +`event.entity.system.platform_family` | string | The entity’s operating system family +`event.entity.system.platform_version` | string | The entity’s operating system version +`event.entity.user` | string | Sensu [RBAC][25] username used by the agent entity + +## Build event filter expressions with JavaScript execution functions + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access built-in JavaScript event filter execution functions in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../../commercial). +{{% /notice %}} + +In addition to [Sensu query expressions][27], Sensu includes several built-in JavaScript functions for event filter execution: + +- `sensu.FetchEvent` +- `sensu.CheckStatus` +- `sensu.ListEvents` + +Use these functions to query your event stores for other events in the same namespace. + +For example, to handle only events for the `server01` entity *and* the `disk` check, use the `sensu.FetchEvent` function in your event filter expressions: + +{{< code javascript >}} +"expressions": [ + '(function () { var diskEvent = sensu.FetchEvent("server01", "disk"); if (diskEvent == nil) { return false; } return diskEvent.check.status == 0; })()' +] +{{< /code >}} + +### `sensu.EventStatus` + +The `sensu.EventStatus` function takes zero or more checks as arguments. +It returns an array of status codes for the events associated with the specified checks. + +If you do not specify any checks, the function always returns an empty array. + +You can refer to the checks as strings: + +{{< code javascript >}} +sensu.EventStatus("database", "disk") +{{< /code >}} + +If you pass the check names as strings, Sensu assumes that the entities are the same as those in the events being filtered. + +You can also refer to the checks in objects that include both the entity and check name. +For example: + +{{< code javascript >}} +sensu.EventStatus({entity: "server01", check: "disk"}, {entity: "server01", check: "database"}) +{{< /code >}} + +In both cases, if no event matches the specified entities and checks, Sensu will raise an error. + +### `sensu.FetchEvent` + +The `sensu.FetchEvent` function loads the Sensu event that corresponds to the specified entity and check names. + +The format is `sensu.FetchEvent(entity, check)`. +For example: + +{{< code javascript >}} +sensu.FetchEvent("server01", "disk") +{{< /code >}} + +You can only load events from the same namespace as the event being filtered. +The returned object uses the same format as responses for the [core/v2/events API][43]. + +If an event does not exist for the specified entity and check names, Sensu will raise an error. + +### `sensu.ListEvents` + +The `sensu.ListEvents` function returns an array of all events in the same namespace as the event being filtered. + +{{% notice note %}} +**NOTE**: If you have many events in the namespace, this function may require a substantial amount of time to return them. +{{% /notice %}} + +For example: + +{{< code javascript >}} +sensu.ListEvents() +{{< /code >}} + +The events in the returned array use the same format as responses for the [core/v2/events API][43]. + +## Event filter specification + +### Top-level attributes + +api_version | +-------------|------ +description | Top-level attribute that specifies the Sensu API group and version. For event filters in this version of Sensu, this attribute should always be `core/v2`. +required | Required for filter definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][33]. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +api_version: core/v2 +{{< /code >}} +{{< code json >}} +{ + "api_version": "core/v2" +} +{{< /code >}} +{{< /language-toggle >}} + +metadata | +-------------|------ +description | Top-level collection of metadata about the event filter, including `name`, `namespace`, and `created_by` as well as custom `labels` and `annotations`. The `metadata` map is always at the top level of the filter definition. This means that in `wrapped-json` and `yaml` formats, the `metadata` scope occurs outside the `spec` scope. Read [metadata attributes][11] for details. +required | Required for filter definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][33]. +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +metadata: + name: filter-weekdays-only + namespace: default + created_by: admin + labels: + region: us-west-1 + annotations: + slack-channel: "#monitoring" +{{< /code >}} +{{< code json >}} +{ + "metadata": { + "name": "filter-weekdays-only", + "namespace": "default", + "created_by": "admin", + "labels": { + "region": "us-west-1" + }, + "annotations": { + "slack-channel": "#monitoring" + } + } +} +{{< /code >}} +{{< /language-toggle >}} + +spec | +-------------|------ +description | Top-level map that includes the event filter [spec attributes][34]. +required | Required for filter definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][33]. +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +spec: + action: allow + expressions: + - event.entity.namespace == 'production' + runtime_assets: [] +{{< /code >}} +{{< code json >}} +{ + "spec": { + "action": "allow", + "expressions": [ + "event.entity.namespace == 'production'" + ], + "runtime_assets": [] + } +} +{{< /code >}} +{{< /language-toggle >}} + +type | +-------------|------ +description | Top-level attribute that specifies the [`sensuctl create`][33] resource type. Event filters should always be type `EventFilter`. +required | Required for filter definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][33]. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +type: EventFilter +{{< /code >}} +{{< code json >}} +{ + "type": "EventFilter" +} +{{< /code >}} +{{< /language-toggle >}} + +### Metadata attributes + +| annotations | | +-------------|------ +description | Non-identifying metadata to include with event data that you can access with event filters. You can use annotations to add data that's meaningful to people or external tools that interact with Sensu.

    In contrast to labels, you cannot use annotations in [API response filtering][36], [sensuctl response filtering][37], or [web UI views][42]. +required | false +type | Map of key-value pairs. Keys and values can be any valid UTF-8 string. +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +annotations: + managed-by: ops + playbook: www.example.url +{{< /code >}} +{{< code json >}} +{ + "annotations": { + "managed-by": "ops", + "playbook": "www.example.url" + } +} +{{< /code >}} +{{< /language-toggle >}} + +| created_by | | +-------------|------ +description | Username of the Sensu user who created the filter or last updated the filter. Sensu automatically populates the `created_by` field when the filter is created or updated. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +created_by: admin +{{< /code >}} +{{< code json >}} +{ + "created_by": "admin" +} +{{< /code >}} +{{< /language-toggle >}} + +| labels | | +-------------|------ +description | Custom attributes to include with event data that you can use for response and web UI view filtering.

    If you include labels in your event data, you can filter [API responses][36], [sensuctl responses][37], and [web UI views][41] based on them. In other words, labels allow you to create meaningful groupings for your data.

    Limit labels to metadata you need to use for response filtering. For complex, non-identifying metadata that you will *not* need to use in response filtering, use annotations rather than labels. +required | false +type | Map of key-value pairs. Keys can contain only letters, numbers, and underscores and must start with a letter. Values can be any valid UTF-8 string. +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +labels: + environment: development + region: us-west-2 +{{< /code >}} +{{< code json >}} +{ + "labels": { + "environment": "development", + "region": "us-west-2" + } +} +{{< /code >}} +{{< /language-toggle >}} + +| name | | +-------------|------ +description | Unique string used to identify the event filter. Filter names cannot contain special characters or spaces (validated with Go regex [`\A[\w\.\-]+\z`][35]). Each filter must have a unique name within its namespace. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +name: filter-weekdays-only +{{< /code >}} +{{< code json >}} +{ + "name": "filter-weekdays-only" +} +{{< /code >}} +{{< /language-toggle >}} + +| namespace | | +-------------|------ +description | Sensu [RBAC namespace][10] that the event filter belongs to. +required | false +type | String +default | `default` +example | {{< language-toggle >}} +{{< code yml >}} +namespace: production +{{< /code >}} +{{< code json >}} +{ + "namespace": "production" +} +{{< /code >}} +{{< /language-toggle >}} + +### Spec attributes + +action | +-------------|------ +description | Action to take with the event if the event filter expressions match. Read [Inclusive and exclusive event filters][1] for more information. +required | true +type | String +allowed values | `allow`, `deny` +example | {{< language-toggle >}} +{{< code yml >}} +action: allow +{{< /code >}} +{{< code json >}} +{ + "action": "allow" +} +{{< /code >}} +{{< /language-toggle >}} + +expressions | +-------------|------ +description | Event filter expressions to be compared with event data. You can reference event metadata without including the `metadata` scope (for example, `event.entity.namespace`).

    In filter expressions, place string values inside single or double quotes. +required | true +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +expressions: +- event.check.team == 'ops' +- event.check.annotations["service_priority"] == 1 +{{< /code >}} +{{< code json >}} +{ + "expressions": [ + "event.check.team == 'ops'", + "event.check.annotations[\"service_priority\"] == 1" + ] +} +{{< /code >}} +{{< /language-toggle >}} + +runtime_assets | | +---------------|------ +description | Dynamic runtime assets to apply to the event filter's execution context. JavaScript files in the lib directory of the dynamic runtime asset will be evaluated. +required | false +type | Array of string +default | [] +example | {{< language-toggle >}} +{{< code yml >}} +runtime_assets: +- underscore +{{< /code >}} +{{< code json >}} +{ + "runtime_assets": [ + "underscore" + ] +} +{{< /code >}} +{{< /language-toggle >}} + +## Use JavaScript libraries with Sensu filters + +You can include JavaScript libraries in their event filter execution context with [dynamic runtime assets][17]. +For instance, if you package underscore.js into a Sensu asset, you can use functions from the underscore library for filter expressions: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: EventFilter +api_version: core/v2 +metadata: + name: deny_if_failure_in_history +spec: + action: deny + expressions: + - _.reduce(event.check.history, function(memo, h) { return (memo || h.status != + 0); }) + runtime_assets: + - underscore +{{< /code >}} + +{{< code json >}} +{ + "type": "EventFilter", + "api_version": "core/v2", + "metadata": { + "name": "deny_if_failure_in_history" + }, + "spec": { + "action": "deny", + "expressions": [ + "_.reduce(event.check.history, function(memo, h) { return (memo || h.status != 0); })" + ], + "runtime_assets": ["underscore"] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Filter for production events + +The following event filter allows handling for only events with a custom entity label `"environment": "production"`: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: EventFilter +api_version: core/v2 +metadata: + name: production_filter +spec: + action: allow + expressions: + - event.entity.labels['environment'] == 'production' +{{< /code >}} + +{{< code json >}} +{ + "type": "EventFilter", + "api_version": "core/v2", + "metadata": { + "name": "production_filter" + }, + "spec": { + "action": "allow", + "expressions": [ + "event.entity.labels['environment'] == 'production'" + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Filter for non-production events + +The following event filter discards events with a custom entity label `"environment": "production"`, allowing handling only for events without an `environment` label or events with `environment` set to something other than `production`. + +{{% notice note %}} +**NOTE**: The value for the `action` attribute is `deny`, so this is an exclusive event filter. +If evaluation returns false, the event is handled. +{{% /notice %}} + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: EventFilter +api_version: core/v2 +metadata: + name: not_production +spec: + action: deny + expressions: + - event.entity.labels['environment'] == 'production' +{{< /code >}} + +{{< code json >}} +{ + "type": "EventFilter", + "api_version": "core/v2", + "metadata": { + "name": "not_production" + }, + "spec": { + "action": "deny", + "expressions": [ + "event.entity.labels['environment'] == 'production'" + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Filter for state change only + +This example demonstrates how to use the `state_change_only` inclusive event filter to reproduce the behavior of a monitoring system that alerts only on state change: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: EventFilter +api_version: core/v2 +metadata: + name: state_change_only +spec: + action: allow + expressions: + - event.check.occurrences == 1 + runtime_assets: [] +{{< /code >}} + +{{< code json >}} +{ + "type": "EventFilter", + "api_version": "core/v2", + "metadata": { + "name": "state_change_only" + }, + "spec": { + "action": "allow", + "expressions": [ + "event.check.occurrences == 1" + ], + "runtime_assets": [] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Filter for repeated events + +In this example, the `filter_interval_60_hourly` event filter will match event data with a check `interval` of `60` seconds _AND_ an `occurrences` value of `1` (the first occurrence) _OR_ any `occurrences` value that is evenly divisible by 60 via a [modulo operator][38] calculation (calculating the remainder after dividing `occurrences` by 60): + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: EventFilter +api_version: core/v2 +metadata: + name: filter_interval_60_hourly +spec: + action: allow + expressions: + - event.check.interval == 60 + - event.check.occurrences == 1 || event.check.occurrences % 60 == 0 + runtime_assets: [] +{{< /code >}} + +{{< code json >}} +{ + "type": "EventFilter", + "api_version": "core/v2", + "metadata": { + "name": "filter_interval_60_hourly" + }, + "spec": { + "action": "allow", + "expressions": [ + "event.check.interval == 60", + "event.check.occurrences == 1 || event.check.occurrences % 60 == 0" + ], + "runtime_assets": [] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +This example will apply the same logic as the previous example but for checks with a 30-second `interval`: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: EventFilter +api_version: core/v2 +metadata: + name: filter_interval_30_hourly +spec: + action: allow + expressions: + - event.check.interval == 30 + - event.check.occurrences == 1 || event.check.occurrences % 120 == 0 + runtime_assets: [] +{{< /code >}} + +{{< code json >}} +{ + "type": "EventFilter", + "api_version": "core/v2", + "metadata": { + "name": "filter_interval_30_hourly" + }, + "spec": { + "action": "allow", + "expressions": [ + "event.check.interval == 30", + "event.check.occurrences == 1 || event.check.occurrences % 120 == 0" + ], + "runtime_assets": [] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Filter to reduce alert fatigue for keepalive events + +This example `keepalive_timeouts` event filter will match event data with an occurrences value of 1 OR any occurrences value that matches 15 minutes via a modulo operator calculation. +This limits keepalive timeout event alerts to the first occurrence and every 15 minutes thereafter. + +This example uses conditional JavaScript logic to check for an entity-level annotation, `keepalive_alert_minutes`, and if it exists, parses the annotation value as an integer. +If the annotation does not exist, the event filter uses 15 minutes for the alert cadence. + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: EventFilter +api_version: core/v2 +metadata: + name: keepalive_timeouts +spec: + action: allow + expressions: + - is_incident + - event.check.occurrences == 1 || event.check.occurrences % parseInt( 60 * ( 'keepalive_alert_minutes' in event.entity.annotations ? parseInt(event.entity.annotations.keepalive_alert_minutes): 15) / event.check.timeout ) == 0 + runtime_assets: [] +{{< /code >}} + +{{< code json >}} +{ + "type": "EventFilter", + "api_version": "core/v2", + "metadata": { + "name": "keepalive_timeouts" + }, + "spec": { + "action": "allow", + "expressions": [ + "is_incident", + "event.check.occurrences == 1 || event.check.occurrences % parseInt( 60 * ( 'keepalive_alert_minutes' in event.entity.annotations ? parseInt(event.entity.annotations.keepalive_alert_minutes): 15) / event.check.timeout ) == 0" + ], + "runtime_assets": [] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Filter for events during office hours only + +This event filter evaluates the event timestamp to determine if the event occurred between 9 AM and 5 PM UTC on a weekday. +Remember that `action` is equal to `allow`, so this is an inclusive event filter. +If evaluation returns false, the event will not be handled. + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: EventFilter +api_version: core/v2 +metadata: + name: nine_to_fiver +spec: + action: allow + expressions: + - weekday(event.timestamp) >= 1 && weekday(event.timestamp) <= 5 + - hour(event.timestamp) >= 9 && hour(event.timestamp) <= 17 + runtime_assets: [] +{{< /code >}} + +{{< code json >}} +{ + "type": "EventFilter", + "api_version": "core/v2", + "metadata": { + "name": "nine_to_fiver" + }, + "spec": { + "action": "allow", + "expressions": [ + "weekday(event.timestamp) >= 1 && weekday(event.timestamp) <= 5", + "hour(event.timestamp) >= 9 && hour(event.timestamp) <= 17" + ], + "runtime_assets": [] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +Add filter expressions that use the [`minute`][39] and [`second`][40] custom functions for more granular control. +For example, if office hours are 8:30 AM to 5:30 PM: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: EventFilter +api_version: core/v2 +metadata: + name: 830_to_530 +spec: + action: allow + expressions: + - weekday(event.timestamp) >= 1 && weekday(event.timestamp) <= 5 + - hour(event.timestamp) >= 8 && minute(event.timestamp) >= 30 + - hour(event.timestamp) <= 17 && minute(event.timestamp) <= 30 + runtime_assets: [] +{{< /code >}} + +{{< code json >}} +{ + "type": "EventFilter", + "api_version": "core/v2", + "metadata": { + "name": "830_to_530" + }, + "spec": { + "action": "allow", + "expressions": [ + "weekday(event.timestamp) >= 1 && weekday(event.timestamp) <= 5", + "hour(event.timestamp) >= 8 && minute(event.timestamp) >= 30", + "hour(event.timestamp) <= 17 && minute(event.timestamp) <= 30" + ], + "runtime_assets": [] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Filter for events not processed within 30 seconds + +This event filter evaluates the event timestamp to determine if the event was created more than 30 seconds since the current time. +In other words, this filter sets a 30-second time budget for event processing so you can identify and handle events that aren't processed within 30 seconds. + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: EventFilter +api_version: core/v2 +metadata: + name: budget_30 +spec: + action: allow + expressions: + - seconds_since(event.timestamp) > 30 + runtime_assets: [] +{{< /code >}} + +{{< code json >}} +{ + "type": "EventFilter", + "api_version": "core/v2", + "metadata": { + "name": "budget_30" + }, + "spec": { + "action": "allow", + "expressions": [ + "seconds_since(event.timestamp) > 30" + ], + "runtime_assets": [] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Disable alerts without a silence + +This filter allows you to disable alerts without creating silences. + +Add the filter name to the `filters` object for any pipeline whose handler you want to control. +To disable alerts, change the filter's `action` attribute value from `allow` to `deny`. + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: EventFilter +api_version: core/v2 +metadata: + name: emergency_alert_control +spec: + action: allow + expressions: + - event.has_check +{{< /code >}} + +{{< code json >}} +{ + "type": "EventFilter", + "api_version": "core/v2", + "metadata": { + "name": "emergency_alert_control" + }, + "spec": { + "action": "allow", + "expressions": [ + "event.has_check" + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + + +[1]: #inclusive-and-exclusive-event-filters +[2]: #when-attributes +[3]: https://github.com/google/re2/wiki/Syntax +[4]: ../../observe-process/send-slack-alerts/ +[5]: ../../observe-process/plan-maintenance/ +[6]: ../../observe-process/silencing/ +[7]: #built-in-filter-is_incident +[8]: ../../observe-schedule/backend/ +[9]: ../../observe-events/events/ +[10]: ../../../operations/control-access/namespaces/ +[11]: #metadata-attributes +[12]: ../../observe-schedule/hooks/ +[13]: ../../observe-schedule/collect-metrics-with-checks/ +[14]: ../../observe-schedule/checks#use-a-proxy-check-to-monitor-a-proxy-entity +[15]: ../../observe-schedule/checks#use-a-proxy-check-to-monitor-multiple-proxy-entities +[16]: ../../observe-schedule/checks#round-robin-checks +[17]: ../../../plugins/assets/ +[18]: ../../observe-entities/entities#system-attributes +[19]: ../../observe-schedule/checks/#metadata-attributes +[20]: ../../observe-events/events/#history-attributes +[21]: ../../observe-schedule/checks#check-scheduling +[22]: ../../observe-process/handlers/ +[23]: ../../observe-events/events#metrics-attributes +[24]: ../../observe-entities/entities#metadata-attributes +[25]: ../../../operations/control-access/rbac/#agent-user +[26]: ../../observe-schedule/agent#keepalive-monitoring +[27]: ../../observe-filter/sensu-query-expressions/ +[28]: ../../observe-events/events#event-format +[29]: ../../observe-events/events#occurrences-and-occurrences-watermark +[30]: ../../observe-filter/reduce-alert-fatigue/ +[31]: https://github.com/robertkrimen/otto +[32]: https://github.com/robertkrimen/otto/blob/master/README.markdown#regular-expression-incompatibility +[33]: ../../../sensuctl/create-manage-resources/#create-resources +[34]: #spec-attributes +[35]: https://regex101.com/r/zo9mQU/2 +[36]: ../../../api/#response-filtering +[37]: ../../../sensuctl/filter-responses/ +[38]: https://en.wikipedia.org/wiki/Modulo_operation +[39]: ../sensu-query-expressions/#minute +[40]: ../sensu-query-expressions/#second +[41]: ../../../web-ui/search#search-for-labels +[42]: ../../../web-ui/search/ +[43]: ../../../api/core/events/ +[44]: ../../../observability-pipeline/ +[45]: ../ +[46]: #event-attributes-available-to-filters +[47]: #check-attributes-available-to-filters +[48]: #entity-attributes-available-to-filters +[49]: ../../observe-process/pipelines/ +[50]: ../../observe-process/pipelines/#workflows-attributes diff --git a/content/sensu-go/6.12/observability-pipeline/observe-filter/reduce-alert-fatigue.md b/content/sensu-go/6.12/observability-pipeline/observe-filter/reduce-alert-fatigue.md new file mode 100644 index 0000000000..a011706400 --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-filter/reduce-alert-fatigue.md @@ -0,0 +1,697 @@ +--- +title: "Reduce alert fatigue with event filters" +linkTitle: "Reduce Alert Fatigue" +guide_title: "Reduce alert fatigue with event filters" +type: "guide" +description: "Here’s how to reduce alert fatigue with Sensu. Learn about Sensu filters, how they reduce alert fatigue, and how to put them into action." +weight: 60 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: observe-filter +--- + +Sensu event filters allow you to filter events destined for one or more event handlers. +Filters evaluate their expressions against the observation data in events to determine whether the event should be passed to an event handler. + +Use event filters to customize alert policies, improve contact routing, eliminate notification noise from recurring events, and filter events from systems in pre-production environments. + +In this guide, you'll learn how to reduce alert fatigue by configuring an event filter named `hourly`. +You'll then add the filter to a [pipeline workflow][12] that includes a handler named `slack` to prevent alerts from being sent to Slack every minute. + +You can take either of two approaches to create the event filter to handle occurrences: use sensuctl or use a filter dynamic runtime asset. + +## Requirements + +To follow this guide, install the Sensu [backend][17], make sure at least one Sensu [agent][21] is running, and configure [sensuctl][22] to connect to the backend as the [`admin` user][23]. + +The examples in this guide rely on the `check_cpu` check from [Monitor server resources with checks][13]. +Before you begin, follow the instructions to [add the `sensu/check-cpu-usage`][19] dynamic runtime asset and the [`check_cpu`][20] check. + +In addition, if you don't already have a Slack handler in place, follow [Send Slack alerts with handlers][3] to create one before continuing with this guide. + +## Configure a Sensu entity + +Every Sensu agent has a defined set of subscriptions that determine which checks the agent will execute. +For an agent to execute a specific check, you must specify the same subscription in the agent configuration and the check definition. + +The examples for both approaches in this guide use the `check_cpu` check from Monitor server resources with checks, which includes the subscription `system`. +Use sensuctl to add a `system` subscription to one of your entities. + +Before you run the following code, replace `` with the name of the entity on your system. + +{{% notice note %}} +**NOTE**: To find your entity name, run `sensuctl entity list`. +The `ID` is the name of your entity. +{{% /notice %}} + +{{< code shell >}} +sensuctl entity update +{{< /code >}} + +- For `Entity Class`, press enter. +- For `Subscriptions`, type `system` and press enter. + +Run this command to confirm both Sensu services are running: + +{{< code shell >}} +systemctl status sensu-backend && systemctl status sensu-agent +{{< /code >}} + +The response should indicate `active (running)` for both the Sensu backend and agent. + +## Approach 1: Use sensuctl to create an event filter + +First, create an event filter called `hourly` that matches new events (where the event's `occurrences` is equal to `1`) or hourly events (every hour after the first occurrence, calculated with the check's `interval` and the event's `occurrences`). + +Events in Sensu Go are handled regardless of check execution status. +Even successful check events are passed through the pipeline, so you'll need to add a clause for non-zero status. + +{{< code shell >}} +sensuctl filter create hourly \ +--action allow \ +--expressions "event.check.occurrences == 1 || event.check.occurrences % (3600 / event.check.interval) == 0" +{{< /code >}} + +You should receive a confirmation message: + +{{< code text >}} +Created +{{< /code >}} + +To view the event filter resource definition, run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl filter info hourly --format yaml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl filter info hourly --format wrapped-json +{{< /code >}} + +{{< /language-toggle >}} + +The event filter definition will be similar to this example: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: EventFilter +api_version: core/v2 +metadata: + name: hourly +spec: + action: allow + expressions: + - event.check.occurrences == 1 || event.check.occurrences % (3600 / event.check.interval) == 0 + runtime_assets: null +{{< /code >}} + +{{< code json >}} +{ + "type": "EventFilter", + "api_version": "core/v2", + "metadata": { + "name": "hourly" + }, + "spec": { + "action": "allow", + "expressions": [ + "event.check.occurrences == 1 || event.check.occurrences % (3600 / event.check.interval) == 0" + ], + "runtime_assets": null + } +} +{{< /code >}} + +{{< /language-toggle >}} + +### Add the event filter to a pipeline + +Now that you've created the `hourly` event filter, you can include it in a new pipeline, along with the `slack` handler created in Send Slack alerts with handlers (see [Requirements][24] if you do not have a handler that sends alerts to a Slack channel). +You'll also include the built-in `is_incident` filter so that only failing events are handled, which will further reduce the number of Slack messages Sensu sends. + +To create a new pipeline that includes the `hourly` and `is_incident` event filters as well as the `slack` handler, run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +echo '--- +type: Pipeline +api_version: core/v2 +metadata: + name: reduce_alerts +spec: + workflows: + - name: slack_alerts + filters: + - name: is_incident + type: EventFilter + api_version: core/v2 + - name: hourly + type: EventFilter + api_version: core/v2 + handler: + name: slack + type: Handler + api_version: core/v2' | sensuctl create +{{< /code >}} + +{{< code shell "JSON" >}} +echo '{ + "type": "Pipeline", + "api_version": "core/v2", + "metadata": { + "name": "reduce_alerts" + }, + "spec": { + "workflows": [ + { + "name": "slack_alerts", + "filters": [ + { + "name": "is_incident", + "type": "EventFilter", + "api_version": "core/v2" + }, + { + "name": "hourly", + "type": "EventFilter", + "api_version": "core/v2" + } + ], + "handler": { + "name": "slack", + "type": "Handler", + "api_version": "core/v2" + } + } + ] + } +}' | sensuctl create +{{< /code >}} + +{{< /language-toggle >}} + +### Assign the pipeline to a check + +To use the `reduce_alerts` pipeline, list it in a check definition's pipelines array. +All the observability events that the check produces will be processed according to the pipeline's workflows. + +In this example, assign your `reduce_alerts` pipeline to the `check_cpu` check to receive Slack alerts when the CPU usage of your system reaches the specific thresholds set in the check command. + +To open the check definition in your text editor, run: + +{{< code shell >}} +sensuctl edit check check_cpu +{{< /code >}} + +Replace the `pipelines: []` line with the following array and save the updated check definition: + +{{< code yml >}} + pipelines: + - type: Pipeline + api_version: core/v2 + name: reduce_alerts +{{< /code >}} + +You should see a response to confirm the update: + +{{< code text >}} +Updated /api/core/v2/namespaces/default/checks/check_cpu +{{< /code >}} + +To view the updated `check_cpu` resource definition, run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl check info check_cpu --format yaml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl check info check_cpu --format wrapped-json +{{< /code >}} + +{{< /language-toggle >}} + +The updated check definition will be similar to this example: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: check_cpu +spec: + check_hooks: null + command: check-cpu-usage -w 75 -c 90 + env_vars: null + handlers: null + high_flap_threshold: 0 + interval: 10 + low_flap_threshold: 0 + output_metric_format: "" + output_metric_handlers: null + pipelines: + - api_version: core/v2 + name: reduce_alerts + type: Pipeline + proxy_entity_name: "" + publish: true + round_robin: false + runtime_assets: + - check-cpu-usage + secrets: null + stdin: false + subdue: null + subscriptions: + - system + timeout: 0 + ttl: 0 +{{< /code >}} + +{{< code json >}} +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "check_cpu" + }, + "spec": { + "check_hooks": null, + "command": "check-cpu-usage -w 75 -c 90", + "env_vars": null, + "handlers": [], + "high_flap_threshold": 0, + "interval": 10, + "low_flap_threshold": 0, + "output_metric_format": "", + "output_metric_handlers": null, + "pipelines": [ + { + "api_version": "core/v2", + "name": "reduce_alerts", + "type": "Pipeline" + } + ], + "proxy_entity_name": "", + "publish": true, + "round_robin": false, + "runtime_assets": [ + "check-cpu-usage" + ], + "secrets": null, + "stdin": false, + "subdue": null, + "subscriptions": [ + "system" + ], + "timeout": 0, + "ttl": 0 + } +} +{{< /code >}} + +{{< /language-toggle >}} + +The check will now send events to the `reduce_alerts` pipeline. +Skip to [Confirm the event filter][15] to learn how to verify that the filter is working. + +## Approach 2: Use an event filter dynamic runtime asset + +In the dynamic runtime asset approach, the first step is to obtain an event filter asset that will allow you to replicate the behavior of the `hourly` event filter created in [Approach 1 via `sensuctl`][4]. + +Use `sensuctl asset add` to register the sensu/sensu-go-fatigue-check-filter dynamic runtime asset: + +{{< code shell >}} +sensuctl asset add sensu/sensu-go-fatigue-check-filter:0.8.1 -r fatigue-filter +{{< /code >}} + +This example uses the `-r` (rename) flag to specify a shorter name for the asset: `fatigue-filter`. + +The response will indicate that the asset was added: + +{{< code text >}} +fetching bonsai asset: sensu/sensu-go-fatigue-check-filter:0.8.1 +added asset: sensu/sensu-go-fatigue-check-filter:0.8.1 + +You have successfully added the Sensu asset resource, but the asset will not get downloaded until +it's invoked by another Sensu resource (ex. check). To add this runtime asset to the appropriate +resource, populate the "runtime_assets" field with ["fatigue-filter"]. +{{< /code >}} + +{{% notice note %}} +**NOTE**: Sensu does not download and install dynamic runtime asset builds onto the system until they are needed for command execution. +{{% /notice %}} + +You've registered the dynamic runtime asset, but you still need to create the filter. + +Create a file named `sensu-fatigue-check-filter.yml` or `sensu-fatigue-check-filter.json` in your Sensu installation to store the event filter definition. +Copy this this filter definition into the file and save it: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: EventFilter +api_version: core/v2 +metadata: + name: fatigue_check +spec: + action: allow + expressions: + - fatigue_check(event) + runtime_assets: + - fatigue-filter +{{< /code >}} + +{{< code json >}} +{ + "type": "EventFilter", + "api_version": "core/v2", + "metadata": { + "name": "fatigue_check" + }, + "spec": { + "action": "allow", + "expressions": [ + "fatigue_check(event)" + ], + "runtime_assets": [ + "fatigue-filter" + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +Then, use sensuctl to create a filter named `fatigue_check` from the file: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl create -f sensu-fatigue-check-filter.yml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl create -f sensu-fatigue-check-filter.json +{{< /code >}} + +{{< /language-toggle >}} + +Now that you've added the dynamic runtime asset and created the event filter definition and pipeline, you can create the check annotations you need for the dynamic runtime asset to work properly. + +### Update a check for filter dynamic runtime asset use + +Next, you'll need to make some additions to any checks you want to use the `fatigue_check` filter with. +All the observability events that the check produces will be processed according to the pipeline's workflows. + +Assign your `reduce_alerts` pipeline to the `check_cpu` check to receive Slack alerts when the CPU usage of your system reaches the specific thresholds set in the check command. + +To open the check definition in your text editor, run: + +{{< code shell >}} +sensuctl edit check check_cpu +{{< /code >}} + +In the check definition, update the `pipelines: []` line with the following array: + +{{< language-toggle >}} + +{{< code shell "YML" >}} + pipelines: + - type: Pipeline + api_version: core/v2 + name: cpu_check_alerts +{{< /code >}} + +{{< code shell "JSON" >}} + "pipelines": [ + { + "type": "Pipeline", + "api_version": "core/v2", + "name": "cpu_check_alerts" + } + ] +{{< /code >}} + +{{< /language-toggle >}} + +Add the following annotations in the check metadata: + +{{< language-toggle >}} + +{{< code shell "YML" >}} + annotations: + fatigue_check/occurrences: '1' + fatigue_check/interval: '3600' + fatigue_check/allow_resolution: 'false' +{{< /code >}} + +{{< code shell "JSON" >}} + "annotations": { + "fatigue_check/occurrences": "1", + "fatigue_check/interval": "3600", + "fatigue_check/allow_resolution": "false" + } +{{< /code >}} + +{{< /language-toggle >}} + +After you add the pipeline array and annotations, save the updated check definition. +To confirm your updates, run this command to retrieve the check definition: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl check info check_cpu --format yaml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl check info check_cpu --format wrapped-json +{{< /code >}} + +{{< /language-toggle >}} + +The check definition should be similar to this example: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: cpu-check + annotations: + fatigue_check/occurrences: '1' + fatigue_check/interval: '3600' + fatigue_check/allow_resolution: 'false' +spec: + command: check-cpu -w 75 c 95 + env_vars: null + handlers: null + high_flap_threshold: 0 + interval: 60 + low_flap_threshold: 0 + output_metric_format: '' + output_metric_handlers: null + output_metric_tags: null + pipelines: + - api_version: core/v2 + name: reduce_alerts + type: Pipeline + proxy_entity_name: '' + publish: true + round_robin: false + runtime_assets: + - check_cpu_usage + stdin: false + subdue: + subscriptions: + - system + timeout: 0 + ttl: 0 +{{< /code >}} + +{{< code json >}} +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "cpu-check", + "annotations": { + "fatigue_check/occurrences": "1", + "fatigue_check/interval": "3600", + "fatigue_check/allow_resolution": "false" + } + }, + "spec": { + "command": "check-cpu -w 75 c 95", + "env_vars": null, + "handlers": [], + "high_flap_threshold": 0, + "interval": 60, + "low_flap_threshold": 0, + "output_metric_format": "", + "output_metric_handlers": null, + "output_metric_tags": null, + "pipelines": [ + { + "api_version": "core/v2", + "name": "reduce_alerts", + "type": "Pipeline" + } + ], + "proxy_entity_name": "", + "publish": true, + "round_robin": false, + "runtime_assets": [ + "check_cpu_usage" + ], + "stdin": false, + "subdue": null, + "subscriptions": [ + "system" + ], + "timeout": 0, + "ttl": 0 + } +}{{< /code >}} + +{{< /language-toggle >}} + +The annotations are required for the filter dynamic runtime asset to work the same way as the interactively created event filter. +Specifically, the annotations in this check definition are doing several things: + +1. `fatigue_check/occurrences`: Tells the event filter on which occurrence to send the event for further processing +2. `fatigue_check/interval`: Tells the event filter the interval at which to allow additional events to be processed (in seconds) +3. `fatigue_check/allow_resolution`: Determines whether to pass a `resolve` event through to the filter + +For more information about configuring these values, read the [Sensu Go Fatigue Check Filter][8] README. +Next, you'll add the newly minted event filter and an existing handler to a pipeline. + +### Add the event filter to a pipeline + +Now that you've created the `fatigue_check` event filter, you can add it to a pipeline along with the `slack` handler created in Send Slack alerts with handlers (see [Requirements][24] if you do not have a handler that sends alerts to a Slack channel). +You'll also add the built-in `is_incident` filter so that only failing events are handled, which will further reduce the number of Slack messages Sensu sends. + +{{< language-toggle >}} + +{{< code shell "YML" >}} +echo '--- +type: Pipeline +api_version: core/v2 +metadata: + name: reduce_alerts +spec: + workflows: + - name: slack_alerts + filters: + - name: is_incident + type: EventFilter + api_version: core/v2 + - name: fatigue_check + type: EventFilter + api_version: core/v2 + handler: + name: slack + type: Handler + api_version: core/v2' | sensuctl create +{{< /code >}} + +{{< code shell "JSON" >}} +echo '{ + "type": "Pipeline", + "api_version": "core/v2", + "metadata": { + "name": "reduce_alerts" + }, + "spec": { + "workflows": [ + { + "name": "slack_alerts", + "filters": [ + { + "name": "is_incident", + "type": "EventFilter", + "api_version": "core/v2" + }, + { + "name": "fatigue_check", + "type": "EventFilter", + "api_version": "core/v2" + } + ], + "handler": { + "name": "slack", + "type": "Handler", + "api_version": "core/v2" + } + } + ] + } +}' | sensuctl create +{{< /code >}} + +{{< /language-toggle >}} + +## Confirm the event filter + +Instead of waiting to receive a Slack alert, you can verify the proper behavior of these event filters with `sensu-backend` logs. +The default location of these logs varies based on your platform. +Read [Troubleshoot Sensu][2] for details about the log location. + +Whenever an event is being handled, two log entries are added: + +{{< code text >}} +"handler":"slack","level":"debug","msg":"sending event to handler" +"msg":"pipelined executed event pipe handler","output":"","status":0 +{{< /code >}} + +However, if the event is being discarded by the event filter, a log entry with the message `event filtered` will appear instead. + +## What's next + +Now that you know how to add event filters to pipelines and use a dynamic runtime asset to help reduce alert fatigue, read the [filters reference][1] for in-depth information about event filters. + +If you're not already familiar with [dynamic runtime assets][6], read [Use assets to install plugins][7]. +This will help you understand what dynamic runtime assets are and how they are used in Sensu. +Read the asset page in Bonsai for details about the [sensu/sensu-go-fatigue-check-filter][8] dynamic runtime asset. + +If you want to share and reuse the `hourly` and `fatigue_check` event filters like code, you can [save them to a file][10] and start building a [monitoring as code repository][11]. + + +[1]: ../filters/ +[2]: ../../../operations/maintain-sensu/troubleshoot#log-file-locations +[3]: ../../observe-process/send-slack-alerts/ +[4]: #approach-1-use-sensuctl-to-create-an-event-filter +[5]: #approach-2-use-an-event-filter-dynamic-runtime-asset +[6]: ../../../plugins/assets/ +[7]: ../../../plugins/use-assets-to-install-plugins/ +[8]: https://bonsai.sensu.io/assets/sensu/sensu-go-fatigue-check-filter +[9]: https://bonsai.sensu.io/ +[10]: ../../../operations/monitoring-as-code/#build-as-you-go +[11]: ../../../operations/monitoring-as-code/ +[12]: ../../observe-process/pipelines/ +[13]: ../../observe-schedule/monitor-server-resources/ +[14]: ../../observe-schedule/checks/#pipelines-attribute +[15]: #confirm-the-event-filter +[16]: ../../observe-schedule/subscriptions/ +[17]: ../../../operations/deploy-sensu/install-sensu/#install-the-sensu-backend +[18]: ../../../sensuctl/ +[19]: ../../observe-schedule/monitor-server-resources/#register-the-sensucheck-cpu-usage-asset +[20]: ../../observe-schedule/monitor-server-resources/#create-a-check-to-monitor-a-server +[21]: ../../../operations/deploy-sensu/install-sensu/#install-sensu-agents +[22]: ../../../operations/deploy-sensu/install-sensu/#install-sensuctl +[23]: ../../../operations/control-access/rbac/#default-users +[24]: #requirements diff --git a/content/sensu-go/6.12/observability-pipeline/observe-filter/route-alerts.md b/content/sensu-go/6.12/observability-pipeline/observe-filter/route-alerts.md new file mode 100644 index 0000000000..49d507e8ac --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-filter/route-alerts.md @@ -0,0 +1,833 @@ +--- +title: "Route alerts with event filters" +linkTitle: "Route Alerts" +guide_title: "Route alerts with event filters" +type: "guide" +description: "Alert the right people using their preferred contact method with Sensu's contact routing and reduce mean time to response and recovery." +weight: 80 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: observe-filter +--- + +Every alert has an ideal first responder: a team or person who knows how to triage and address the issue. +Sensu contact routing lets you alert the right people using their preferred contact methods and reduce mean time to response and recovery. + +In this guide, you'll set up alerts for two teams (dev and ops) with separate Slack channels. +Each team wants to be alerted only for the things they care about, using their team's Slack channel. +There's also a fallback option for alerts that should not be routed to either the dev or ops team. +To achieve this, you'll use a [pipeline][16] resource with three workflows, one for each contact option. + +Routing alerts requires three types of Sensu resources: + +- **Handlers** to store contact preferences for the dev and ops teams, plus a fallback option +- **Event filters** to match contact labels to the right handler +- A **pipeline** to organize the event filters and handlers into workflows that route alerts to the right contacts + +Here's a quick overview of the configuration to set up contact routing with a pipeline. +Two of the check definitions include a `contacts` label, which allows the pipeline to route alerts to the correct Slack channel based each workflow's event filter and handler. + +{{< figure src="/images/go/route_alerts/contact_routing_pipeline.png" alt="Diagram that shows events generated with and without labels, matched to the appropriate handler using a contact filter and routed to the appropriate Slack channel" link="/images/go/route_alerts/contact_routing_pipeline.png" target="_blank" >}} + + +## Requirements + +To follow this guide, install the Sensu [backend][1], make sure at least one Sensu [agent][23] is running, and configure [sensuctl][22] to connect to the backend as the [`admin` user][24]. + +You will also need [cURL][5], a [Slack webhook URL][6], and three different Slack channels to receive test alerts (one for each team). + +The examples in this guide rely on the `check_cpu` check from [Monitor server resources with checks][27]. +Before you begin, follow the instructions to [add the `sensu/check-cpu-usage`][28] dynamic runtime asset and the [`check_cpu`][29] check. + +## Configure a Sensu entity + +Every Sensu agent has a defined set of subscriptions that determine which checks the agent will execute. +For an agent to execute a specific check, you must specify the same subscription in the agent configuration and the check definition. + +This guide uses an example check that includes the subscription `system`. +Use sensuctl to add a `system` subscription to one of your entities. + +Before you run the following code, replace `` with the name of the entity on your system. + +{{% notice note %}} +**NOTE**: To find an entity's name, run `sensuctl entity list`. +The `ID` is the name of the entity. +{{% /notice %}} + +{{< code shell >}} +sensuctl entity update +{{< /code >}} + +- For `Entity Class`, press enter. +- For `Subscriptions`, type `system` and press enter. + +Run this command to confirm both Sensu services are running: + +{{< code shell >}} +systemctl status sensu-backend && systemctl status sensu-agent +{{< /code >}} + +The response should indicate `active (running)` for both the Sensu backend and agent. + +## Register dynamic runtime assets + +Contact routing is powered by the sensu/sensu-go-has-contact-filter dynamic runtime asset. +To add the asset to Sensu, use sensuctl asset add: + +{{< code shell >}} +sensuctl asset add sensu/sensu-go-has-contact-filter:0.3.0 -r contact-filter +{{< /code >}} + +The response will indicate that the asset was added: + +{{< code text >}} +fetching bonsai asset: sensu/sensu-go-has-contact-filter:0.3.0 +added asset: sensu/sensu-go-has-contact-filter:0.3.0 + +You have successfully added the Sensu asset resource, but the asset will not get downloaded until +it's invoked by another Sensu resource (ex. check). To add this runtime asset to the appropriate +resource, populate the "runtime_assets" field with ["contact-filter"]. +{{< /code >}} + +This example uses the `-r` (rename) flag to specify a shorter name for the asset: `contact-filter`. + +Next, add the sensu/sensu-slack-handler dynamic runtime asset to Sensu with sensuctl: + +{{< code shell >}} +sensuctl asset add sensu/sensu-slack-handler:1.5.0 -r sensu-slack-handler +{{< /code >}} + +The response will confirm that the asset was added: + +{{< code text >}} +fetching bonsai asset: sensu/sensu-slack-handler:1.5.0 -r sensu-slack-handler +added asset: sensu/sensu-slack-handler:1.5.0 + +You have successfully added the Sensu asset resource, but the asset will not get downloaded until +it's invoked by another Sensu resource (ex. check). To add this runtime asset to the appropriate +resource, populate the "runtime_assets" field with ["sensu-slack-handler"]. +{{< /code >}} + +This example uses the `-r` (rename) flag to specify a shorter name for the dynamic runtime asset: `sensu-slack-handler`. + +Run `sensuctl asset list` to confirm that the dynamic runtime assets are ready to use. +The response will confirm the available assets: + +{{< code text >}} + Name URL Hash +────────────────────── ───────────────────────────────────────────────────────────────────────────── ────────── + contact-filter //assets.bonsai.sensu.io/.../sensu-go-has-contact-filter_0.3.0.tar.gz d35c6c4 + sensu-slack-handler //assets.bonsai.sensu.io/.../sensu-slack-handler_1.0.3_windows_amd64.tar.gz 53359fa + sensu-slack-handler //assets.bonsai.sensu.io/.../sensu-slack-handler_1.0.3_darwin_386.tar.gz e2d7d0d + sensu-slack-handler //assets.bonsai.sensu.io/.../sensu-slack-handler_1.0.3_linux_armv7.tar.gz 362fe51 + sensu-slack-handler //assets.bonsai.sensu.io/.../sensu-slack-handler_1.0.3_linux_arm64.tar.gz b492ae2 + sensu-slack-handler //assets.bonsai.sensu.io/.../sensu-slack-handler_1.0.3_darwin_amd64.tar.gz 88bbdca + sensu-slack-handler //assets.bonsai.sensu.io/.../sensu-slack-handler_1.0.3_linux_386.tar.gz d9040ae + sensu-slack-handler //assets.bonsai.sensu.io/.../sensu-slack-handler_1.0.3_linux_amd64.tar.gz 6872086 +{{< /code >}} + +{{% notice note %}} +**NOTE**: Sensu does not download and install dynamic runtime asset builds onto the system until they are needed for command execution. +{{% /notice %}} + +## Create contact filters + +The sensu/sensu-go-has-contact-filter dynamic runtime asset supports two functions: + +- `has_contact`, which takes the Sensu event and the contact name as arguments +- `no_contact`, which is available as a fallback in the absence of contact labels and takes only the event as an argument + +You'll use these functions to create event filters that represent the three actions that the Sensu Slack handler can take on an event: contact the ops team, contact the dev team, and contact the fallback option. + +| event filter name | expression | description +| --- | --- | --- | +| `contact_ops` | `has_contact(event, "ops")` | Allow events with the entity or check label `contacts: ops` +| `contact_dev` | `has_contact(event, "dev")` | Allow events with the entity or check label `contacts: dev` +| `contact_fallback` | `no_contacts(event)` | Allow events without an entity or check `contacts` label + +Use sensuctl to create the three event filters: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +echo '--- +type: EventFilter +api_version: core/v2 +metadata: + name: contact_ops +spec: + action: allow + runtime_assets: + - contact-filter + expressions: + - has_contact(event, "ops") +--- +type: EventFilter +api_version: core/v2 +metadata: + name: contact_dev +spec: + action: allow + runtime_assets: + - contact-filter + expressions: + - has_contact(event, "dev") +--- +type: EventFilter +api_version: core/v2 +metadata: + name: contact_fallback +spec: + action: allow + runtime_assets: + - contact-filter + expressions: + - no_contacts(event)' | sensuctl create +{{< /code >}} + +{{< code shell "JSON" >}} +echo '{ + "type": "EventFilter", + "api_version": "core/v2", + "metadata": { + "name": "contact_ops" + }, + "spec": { + "action": "allow", + "runtime_assets": [ + "contact-filter" + ], + "expressions": [ + "has_contact(event, \"ops\")" + ] + } +} +{ + "type": "EventFilter", + "api_version": "core/v2", + "metadata": { + "name": "contact_dev" + }, + "spec": { + "action": "allow", + "runtime_assets": [ + "contact-filter" + ], + "expressions": [ + "has_contact(event, \"dev\")" + ] + } +} +{ + "type": "EventFilter", + "api_version": "core/v2", + "metadata": { + "name": "contact_fallback" + }, + "spec": { + "action": "allow", + "runtime_assets": [ + "contact-filter" + ], + "expressions": [ + "no_contacts(event)" + ] + } +}' | sensuctl create +{{< /code >}} + +{{< /language-toggle >}} + +Use sensuctl to confirm that the event filters were added: + +{{< code shell >}} +sensuctl filter list +{{< /code >}} + +The response should list the new `contact_ops`, `contact_dev`, and `contact_fallback` event filters: + +{{< code text >}} + Name Action Expressions + ────────────────── ──────── ───────────────────────────── + contact_dev allow (has_contact(event, "dev")) + contact_fallback allow (no_contacts(event)) + contact_ops allow (has_contact(event, "ops")) +{{< /code >}} + +## Create a handler for each contact + +With your contact filters in place, you can create a handler for each contact: ops, dev, and fallback. +In each handler definition, you will specify: + +- A unique name: `ops_handler`, `dev_handler`, or `fallback_handler` +- A customized command with the contact's preferred Slack channel +- An environment variable that contains your Slack webhook URL +- The `sensu-slack-handler` dynamic runtime asset + +Before you run the following code to create the handlers with sensuctl, make these changes: + +- Replace ``, ``, and `` with the names of the channels you want to use to receive alerts in your Slack instance. +- Replace `` with your Slack webhook URL. + +After you update the code to use your preferred Slack channels and webhook URL, run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +echo '--- +type: Handler +api_version: core/v2 +metadata: + name: ops_handler +spec: + command: sensu-slack-handler --channel "#" + env_vars: + - SLACK_WEBHOOK_URL=https://hooks.slack.com/services/xxxxxxxxx + handlers: null + runtime_assets: + - sensu-slack-handler + secrets: null + timeout: 0 + type: pipe +--- +type: Handler +api_version: core/v2 +metadata: + name: dev_handler +spec: + command: sensu-slack-handler --channel "#" + env_vars: + - SLACK_WEBHOOK_URL=https://hooks.slack.com/services/xxxxxxxxx + handlers: null + runtime_assets: + - sensu-slack-handler + secrets: null + timeout: 0 + type: pipe +--- +type: Handler +api_version: core/v2 +metadata: + name: fallback_handler +spec: + command: sensu-slack-handler --channel "#" + env_vars: + - SLACK_WEBHOOK_URL=https://hooks.slack.com/services/xxxxxxxxx + handlers: null + runtime_assets: + - sensu-slack-handler + secrets: null + timeout: 0 + type: pipe' | sensuctl create +{{< /code >}} + +{{< code shell "JSON" >}} +echo '{ + "type": "Handler", + "api_version": "core/v2", + "metadata": { + "name": "ops_handler" + }, + "spec": { + "command": "sensu-slack-handler --channel \"#\"", + "env_vars": [ + "SLACK_WEBHOOK_URL=https://hooks.slack.com/services/xxxxxxxxx" + ], + "handlers": null, + "runtime_assets": [ + "sensu-slack-handler" + ], + "secrets": null, + "timeout": 0, + "type": "pipe" + } +} +{ + "type": "Handler", + "api_version": "core/v2", + "metadata": { + "name": "dev_handler" + }, + "spec": { + "command": "sensu-slack-handler --channel \"#\"", + "env_vars": [ + "SLACK_WEBHOOK_URL=https://hooks.slack.com/services/xxxxxxxxx" + ], + "handlers": null, + "runtime_assets": [ + "sensu-slack-handler" + ], + "secrets": null, + "timeout": 0, + "type": "pipe" + } +} +{ + "type": "Handler", + "api_version": "core/v2", + "metadata": { + "name": "fallback_handler" + }, + "spec": { + "command": "sensu-slack-handler --channel \"#\"", + "env_vars": [ + "SLACK_WEBHOOK_URL=https://hooks.slack.com/services/xxxxxxxxx" + ], + "handlers": null, + "runtime_assets": [ + "sensu-slack-handler" + ], + "secrets": null, + "timeout": 0, + "type": "pipe" + } +}' | sensuctl create +{{< /code >}} + +{{< /language-toggle >}} + +Use sensuctl to confirm that the handlers were added: + +{{< code shell >}} +sensuctl handler list +{{< /code >}} + +The response should list the new `dev_handler`, `ops_handler`, and `fallback_handler` handlers: + +{{< code text >}} + Name Type Timeout Filters Mutator Execute Environment Variables Assets +─────────────────── ────── ───────── ───────── ───────── ───────────────────────────────────────────────────────── ───────────────────────────────────────────────────────────── ────────────────────── + dev_handler pipe 0 RUN:  sensu-slack-handler --channel "#" SLACK_WEBHOOK_URL=https://hooks.slack.com/services/xxxxxxxxx sensu-slack-handler + fallback_handler pipe 0 RUN:  sensu-slack-handler --channel "#" SLACK_WEBHOOK_URL=https://hooks.slack.com/services/xxxxxxxxx sensu-slack-handler + ops_handler pipe 0 RUN:  sensu-slack-handler --channel "#" SLACK_WEBHOOK_URL=https://hooks.slack.com/services/xxxxxxxxx sensu-slack-handler +{{< /code >}} + +## Create a pipeline + +Create a pipeline with a three workflows: one for each contact group. + +Each workflow includes the contact event filter and the corresponding handler for one contact group. +All of the workflows also include the built-in is_incident event filter to reduce noise. + +{{< language-toggle >}} + +{{< code shell "YML" >}} +echo '--- +type: Pipeline +api_version: core/v2 +metadata: + name: slack_contact_routing +spec: + workflows: + - name: dev + filters: + - name: contact_dev + type: EventFilter + api_version: core/v2 + - name: is_incident + type: EventFilter + api_version: core/v2 + handler: + name: dev_handler + type: Handler + api_version: core/v2 + - name: ops + filters: + - name: contact_ops + type: EventFilter + api_version: core/v2 + - name: is_incident + type: EventFilter + api_version: core/v2 + handler: + name: ops_handler + type: Handler + api_version: core/v2 + - name: fallback + filters: + - name: contact_fallback + type: EventFilter + api_version: core/v2 + - name: is_incident + type: EventFilter + api_version: core/v2 + handler: + name: fallback_handler + type: Handler + api_version: core/v2' | sensuctl create +{{< /code >}} + +{{< code shell "JSON" >}} +echo '{ + "type": "Pipeline", + "api_version": "core/v2", + "metadata": { + "name": "slack_contact_routing" + }, + "spec": { + "workflows": [ + { + "name": "dev", + "filters": [ + { + "name": "contact_dev", + "type": "EventFilter", + "api_version": "core/v2" + }, + { + "name": "is_incident", + "type": "EventFilter", + "api_version": "core/v2" + } + ], + "handler": { + "name": "dev_handler", + "type": "Handler", + "api_version": "core/v2" + } + }, + { + "name": "ops", + "filters": [ + { + "name": "contact_ops", + "type": "EventFilter", + "api_version": "core/v2" + }, + { + "name": "is_incident", + "type": "EventFilter", + "api_version": "core/v2" + } + ], + "handler": { + "name": "ops_handler", + "type": "Handler", + "api_version": "core/v2" + } + }, + { + "name": "fallback", + "filters": [ + { + "name": "contact_fallback", + "type": "EventFilter", + "api_version": "core/v2" + }, + { + "name": "is_incident", + "type": "EventFilter", + "api_version": "core/v2" + } + ], + "handler": { + "name": "fallback_handler", + "type": "Handler", + "api_version": "core/v2" + } + } + ] + } +}' | sensuctl create +{{< /code >}} + +{{< /language-toggle >}} + +With your pipeline in place, you can send ad hoc events to test your configuration and make sure the right contact groups receive the right alerts in Slack. + +## Send events to test your configuration + +Use the agent API to create ad hoc events and send them to your Slack pipeline. + +First, create an event without a `contacts` label. +You may need to modify the URL with your Sensu agent address. + +{{< code shell "JSON" >}} +curl -X POST \ +-H 'Content-Type: application/json' \ +-d '{ + "check": { + "metadata": { + "name": "example-check-fallback" + }, + "status": 1, + "output": "You should receive this example event in the Slack channel specified by your fallback handler." + }, + "pipelines": [ + { + "type": "Pipeline", + "api_version": "core/v2", + "name": "contact_routing" + } + ] +}' \ +http://127.0.0.1:3031/events +{{< /code >}} + +Since this event doesn't include a `contacts` label, you should also receive an alert in the Slack channel specified in your `fallback_handler` handler. +Behind the scenes, Sensu uses the `contact_fallback` filter to match the event to the `fallback_handler` handler. + +Now, create an event with a `contacts` label: + +{{< code shell "JSON" >}} +curl -X POST \ +-H 'Content-Type: application/json' \ +-d '{ + "check": { + "metadata": { + "name": "example-check-dev", + "labels": { + "contacts": "dev" + } + }, + "status": 1, + "output": "You should receive this example event in the Slack channel specified by your dev handler." + }, + "pipelines": [ + { + "type": "Pipeline", + "api_version": "core/v2", + "name": "contact_routing" + } + ] +}' \ +http://127.0.0.1:3031/events +{{< /code >}} + +Because this event contains the `contacts: dev` label, you should receive an alert in the Slack channel specified by the `dev_handler` handler. + +Resolve the events by sending the same API requests with `status` set to `0`. + +## Manage contact labels in checks and entities + +To assign a check's alerts to a contact, you can add the `contacts` labels to checks or entities. + +### Route contacts with checks + +To test contact routing with check-generated events, update the `check_cpu` check to include the `ops` and `dev` contacts and the `slack_contact_routing` pipeline. + +Use sensuctl to open the check in a text editor: + +{{< code shell >}} +sensuctl edit check check_cpu +{{< /code >}} + +Edit the check metadata to add the following labels: + +{{< language-toggle >}} + +{{< code yml >}} +labels: + contacts: dev, ops +{{< /code >}} + +{{< code json >}} +{ + "labels": { + "contacts": "dev, ops" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +Update the pipelines array to add `slack_contact_routing`: + +{{< language-toggle >}} + +{{< code yml >}} +pipelines: + - type: Pipeline + api_version: core/v2 + name: slack_contact_routing +{{< /code >}} + +{{< code json >}} +{ + "pipelines": { + "type": "Pipeline", + "api_version": "core/v2", + "name": "slack_contact_routing" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +Save and close the updated check definition. +A response will confirm the check was updated. +For example: + +{{< code text >}} +Updated /api/core/v2/namespaces/default/checks/check_cpu +{{< /code >}} + +To view the updated resource definition for `check_cpu` and confirm that it includes the `contacts` labels and `slack_contact_routing` pipeline, run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl check info check_cpu --format yaml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl check info check_cpu --format wrapped-json +{{< /code >}} + +{{< /language-toggle >}} + +The sensuctl response will include the updated `check_cpu` resource definition in the specified format: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: CheckConfig +api_version: core/v2 +metadata: + created_by: admin + labels: + contacts: dev, ops + name: check_cpu + namespace: default +spec: + check_hooks: null + command: check-cpu-usage -w 75 -c 90 + env_vars: null + handlers: [] + high_flap_threshold: 0 + interval: 60 + low_flap_threshold: 0 + output_metric_format: "" + output_metric_handlers: null + pipelines: + - api_version: core/v2 + name: slack_contact_routing + type: Pipeline + proxy_entity_name: "" + publish: true + round_robin: false + runtime_assets: + - check-cpu-usage + secrets: null + stdin: false + subdue: null + subscriptions: + - system + timeout: 0 + ttl: 0 +{{< /code >}} + +{{< code json >}} +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "check_cpu", + "namespace": "default", + "labels": { + "contacts": "dev, ops" + }, + "created_by": "admin" + }, + "spec": { + "check_hooks": null, + "command": "check-cpu-usage -w 75 -c 90", + "env_vars": null, + "handlers": [], + "high_flap_threshold": 0, + "interval": 60, + "low_flap_threshold": 0, + "output_metric_format": "", + "output_metric_handlers": null, + "pipelines": [ + { + "api_version": "core/v2", + "name": "slack_contact_routing", + "type": "Pipeline" + } + ], + "proxy_entity_name": "", + "publish": true, + "round_robin": false, + "runtime_assets": [ + "check-cpu-usage" + ], + "secrets": null, + "stdin": false, + "subdue": null, + "subscriptions": [ + "system" + ], + "timeout": 0, + "ttl": 0 + } +} +{{< /code >}} + +{{< /language-toggle >}} + +Now when the `check_cpu` check generates an event, Sensu will filter the event according to the `contact_dev` and `contact_ops` event filters and send alerts to the #dev and #ops Slack channels: + +{{< figure src="/images/go/route_alerts/contact_routing_dev_ops_teams.png" alt="Diagram that shows an event generated with a check label for the dev and ops teams, matched to the dev team and ops team handlers using contact filters, and routed to the Slack channels for dev and ops" link="/images/go/route_alerts/contact_routing_dev_ops_teams.png" target="_blank" >}} + + +### Entities + +You can specify contacts in entity labels instead of in check labels. +The check definition should still include the pipeline. + +If contact labels are present in both the check and entity, the check contacts override the entity contacts. +In this example, the `dev` label in the check configuration overrides the `ops` label in the agent definition, resulting in an alert sent to #dev but not to #ops or #fallback: + +{{< figure src="/images/go/route_alerts/contact_routing_label_override.png" alt="Diagram that shows how check labels override entity labels when both are present in an event" link="/images/go/route_alerts/contact_routing_label_override.png" target="_blank" >}} + + +## What's next + +Now that you've set up contact routing for two example teams, you can create additional filters, handlers, and labels to represent your team's contacts. +Learn how to use Sensu to [Reduce alert fatigue][11]. + +Read more about the Sensu features you used in this guide: + +- [Subscriptions][21] +- [sensuctl][7] +- [Dynamic runtime assets][26], [Bonsai][25], [sensu/sensu-go-has-contact-filter][12], and [sensu/sensu-slack-handler][8] +- [is_incident event filter][20] +- [Agent API][13] +- [Entity labels][10] + +Save the event filter, handler, and check definitions you created in this guide to YAML or JSON files to start developing a [monitoring as code][15] repository. +Storing your Sensu configurations the same way you would store code means they are portable and repeatable. +Monitoring as code makes it possible to reproduce an environment's configuration and move to a more robust deployment without losing what you’ve started. + + +[1]: ../../../operations/deploy-sensu/install-sensu/#install-the-sensu-backend +[5]: https://curl.haxx.se/ +[6]: https://api.slack.com/incoming-webhooks +[7]: ../../../sensuctl/ +[8]: https://bonsai.sensu.io/assets/sensu/sensu-slack-handler +[9]: ../../observe-schedule/monitor-server-resources/ +[10]: ../../observe-entities/entities/#manage-entity-labels +[11]: ../reduce-alert-fatigue/ +[12]: https://bonsai.sensu.io/assets/sensu/sensu-go-has-contact-filter +[13]: ../../observe-schedule/agent/#create-observability-events-using-the-agent-api +[14]: ../../../sensuctl/sensuctl-bonsai/#install-dynamic-runtime-asset-definitions +[15]: ../../../operations/monitoring-as-code/ +[16]: ../../observe-process/pipelines/ +[17]: #configure-contact-routing-with-a-handler-set +[18]: #1-register-dynamic-runtime-assets +[19]: #2-create-contact-filters +[20]: ../filters/#built-in-filter-is_incident +[21]: ../../observe-schedule/subscriptions/ +[22]: ../../../operations/deploy-sensu/install-sensu/#install-sensuctl +[23]: ../../../operations/deploy-sensu/install-sensu/#install-sensu-agents +[24]: ../../../operations/control-access/rbac/#default-users +[25]: https://bonsai.sensu.io/ +[26]: ../../../plugins/assets/ +[27]: ../../observe-schedule/monitor-server-resources/ +[28]: ../../observe-schedule/monitor-server-resources/#register-the-sensucheck-cpu-usage-asset +[29]: ../../observe-schedule/monitor-server-resources/#create-a-check-to-monitor-a-server diff --git a/content/sensu-go/6.12/observability-pipeline/observe-filter/sensu-query-expressions.md b/content/sensu-go/6.12/observability-pipeline/observe-filter/sensu-query-expressions.md new file mode 100644 index 0000000000..57ce1c6186 --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-filter/sensu-query-expressions.md @@ -0,0 +1,249 @@ +--- +title: "Sensu query expressions reference" +linkTitle: "Sensu Query Expressions Reference" +reference_title: "Sensu query expressions" +type: "reference" +description: "Use JavaScript-based Sensu query expressions to provide additional event filter functionality so you can directly evaluate Sensu resources." +weight: 40 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: observe-filter +--- + +Sensu query expressions (SQEs) are JavaScript-based expressions that provide additional functionality for using Sensu, like nested parameters and custom functions. + +SQEs are defined in [event filters][3], so they act in the context of determining whether a given event should be passed to the handler. +SQEs always receive a single event and some information about that event, like `event.timestamp` or `event.check.interval`. + +SQEs always return either `true` or `false`. +They are evaluated by the [Otto JavaScript VM][1] as JavaScript programs. + +## Syntax quick reference + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    operatordescription
    ===Identity
    !==Nonidentity
    ==Equality
    !=Inequality
    &&Logical AND
    ||Logical OR
    <Less than
    >Greater than
    <=Less than or equal to
    >=Greater than or equal to
    + +## Specification + +SQEs are valid ECMAScript 5 (JavaScript) expressions that return either `true` or `false`. +Other values are not allowed. +If an SQE returns a value besides `true` or `false`, an error is recorded in the [Sensu backend log][2] and the filter evaluates to `false`. + +## Custom functions for weekday, hour, minute, and second + +Together, the `weekday`, `hour`, `minute`, and `second` custom functions provide granular control of time-based filter expressions, comparable to cron scheduling. + +### weekday + +The custom function `weekday` returns a number that represents the day of the week of a UNIX epoch time. +Sunday is `0`. + +For example, if an `event.timestamp` equals 1520275913, which is Monday, March 5, 2018 6:51:53 PM UTC, the following SQE returns `false`: + +{{< code go >}} +weekday(event.timestamp) == 0 +{{< /code >}} + +### hour + +The custom function `hour` returns the hour of a UNIX epoch time (in UTC and 24-hour time notation). + +For example, if an `event.timestamp` equals 1520275913, which is Monday, March 5, 2018 6:51:53 PM UTC, the following SQE returns `true`: + +{{< code go >}} +hour(event.timestamp) >= 17 +{{< /code >}} + +### minute + +The custom function `minute` returns the minute of the hour (0 through 59) of a UNIX epoch time in UTC and 24-hour time notation. + +For example, if an `event.timestamp` equals 1520275913, which is Monday, March 5, 2018 6:51:53 PM UTC, the following SQE returns `false`: + +{{< code go >}} +minute(event.timestamp) <= 30 +{{< /code >}} + +### second + +The custom function `second` returns the second of the minute (0 through 59) of a UNIX epoch time in UTC and 24-hour time notation. + +For example, if an `event.timestamp` equals 1520275913, which is Monday, March 5, 2018 6:51:53 PM UTC, the following SQE returns `true`: + +{{< code go >}} +second(event.timestamp) >= 30 +{{< /code >}} + +## seconds_since custom function + +The custom function `seconds_since` returns the number of seconds (using float64) between the current time and an event's timestamp. + +For systems with event processing pressure, you can use `seconds_since` to create alerts for events that are not handled within a certain period. +For example, the following SQE represents a 30-second time budget for event processing: + +{{< code go >}} +seconds_since(event.timestamp) > 30 +{{< /code >}} + +## sensu.CheckDependencies custom function + +Use the `sensu.CheckDependencies` SQE to filter events based on the results of a different check. + +The `sensu.CheckDependencies` SQE takes zero or more checks as arguments against the event being filtered. +It returns `true` if all the specified checks are passing or `false` if any of the specified checks are failing. + +If you do not specify any checks, the `sensu.CheckDependencies` SQE always returns `true`. +If no event matches the specified checks, Sensu will raise an error. + +You can refer to checks as strings, objects, arrays of strings, and arrays of objects in the `sensu.CheckDependencies` SQE. +If you pass the check names as strings, Sensu assumes that the entities are the same as those in the events being filtered. +You can also pass entity names and check names in objects to reference checks on specific entities. + +### String example + +In this example, if all checks named `database` or `disk` are passing, the SQE returns `true`: + +{{< code javascript >}} +sensu.CheckDependencies("database", "disk") +{{< /code >}} + +### Object example + +You can refer to the checks in objects that include both the entity and check name. +For example: + +{{< code javascript >}} +sensu.CheckDependencies({entity: "server01", check: "disk"}, {entity: "server01", check: "database"}) +{{< /code >}} + +### String and object example + +This example mixes string and object references in the same expression. +It passes a check name (`disk`) as well as an object that includes entity and check names: + +{{< code javascript >}} +sensu.CheckDependencies("disk", {entity: "server01", check: "database"}) +{{< /code >}} + +### Array examples + +You can use `sensu.CheckDependencies` to evaluate a check that contains an array of elements, which is useful for evaluating arrays parsed from event annotations. + +This example references an array of three check names: + +{{< code javascript >}} +sensu.CheckDependencies(["port1", "port2", "port3"]) +{{< /code >}} + +This example references an array of objects that each include both an entity and a check name: + +{{< code javascript >}} +sensu.CheckDependencies([{entity: "router", check: "port1"}, {entity: "router", check: "port2"}]) +{{< /code >}} + +## Examples + +### Evaluate an event attribute + +This SQE returns `true` if the event's entity contains a custom attribute named `namespace` that is equal to `production`: + +{{< code go >}} +event.entity.namespace == 'production' +{{< /code >}} + +### Evaluate an array + +To evaluate an attribute that contains an array of elements, use the `.indexOf` method. +For example, this expression returns `true` if an entity includes the subscription `system`: + +{{< code go >}} +entity.subscriptions.indexOf('system') >= 0 +{{< /code >}} + +### Evaluate the day of the week + +This expression returns `true` if the event occurred on a weekday: + +{{< code go >}} +weekday(event.timestamp) >= 1 && weekday(event.timestamp) <= 5 +{{< /code >}} + +### Evaluate office hours + +This expression returns `true` if the event occurred between 9 AM and 5 PM UTC: + +{{< code go >}} +hour(event.timestamp) >= 9 && hour(event.timestamp) <= 17 +{{< /code >}} + +### Evaluate labels and annotations + +Although you can use annotations to create SQEs, we recommend using labels because labels provide identifying information. + +This expression returns `true` if the event's entity includes the label `webserver`: + +{{< code go >}} +!!event.entity.labels.webserver +{{< /code >}} + +Likewise, this expression returns `true` if the event's entity includes the annotation `www.company.com`: + +{{< code go >}} +!!event.entity.annotations['www.company.com'] +{{< /code >}} + + +[1]: https://github.com/robertkrimen/otto +[2]: ../../observe-schedule/backend/#event-logging +[3]: ../filters/#build-event-filter-expressions-with-sensu-query-expressions diff --git a/content/sensu-go/6.12/observability-pipeline/observe-process/_index.md b/content/sensu-go/6.12/observability-pipeline/observe-process/_index.md new file mode 100644 index 0000000000..ea4c00d9d0 --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-process/_index.md @@ -0,0 +1,174 @@ +--- +title: "Process your observation data" +linkTitle: "Process" +description: "Learn how the process stage of Sensu's observability pipeline works to take actions on your data, like sending incidents to Slack or metrics to InfluxDB." +product: "Sensu Go" +version: "6.12" +weight: 70 +layout: "single" +toc: true +menu: + sensu-go-6.12: + parent: observability-pipeline + identifier: observe-process +--- + + + + +** or click any element in the pipeline to jump to it.** + +**In the process stage, Sensu executes [pipelines][14] and [handlers][1]**. + +In the process stage of Sensu's observability pipeline, the Sensu backend executes [pipelines][14] and [handlers][1] to take action on your observation data. +Your pipeline or handler configuration determines what happens to the events that comes through your observability pipeline. +For example, your pipeline or handler might route incidents to a specific Slack channel or PagerDuty notification workflow, or send metrics to InfluxDB or Prometheus. + +## Pipelines + +[Pipelines][14] are Sensu resources composed of observation event processing workflows made up of filters, mutators, and handlers. +Instead of specifying filters and mutators in handler definitions, you can specify all three in a single pipeline workflow. + +This example shows a pipeline resource definition that includes an event filter, a mutator, and a handler: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Pipeline +api_version: core/v2 +metadata: + name: incident_alerts +spec: + workflows: + - name: labeled_email_alerts + filters: + - name: is_incident + type: EventFilter + api_version: core/v2 + mutator: + name: add_labels + type: Mutator + api_version: core/v2 + handler: + name: email + type: Handler + api_version: core/v2 +{{< /code >}} + +{{< code json >}} +{ + "type": "Pipeline", + "api_version": "core/v2", + "metadata": { + "name": "incident_alerts" + }, + "spec": { + "workflows": [ + { + "name": "labeled_email_alerts", + "filters": [ + { + "name": "state_change_only", + "type": "EventFilter", + "api_version": "core/v2" + } + ], + "mutator": { + "name": "add_labels", + "type": "Mutator", + "api_version": "core/v2" + }, + "handler": { + "name": "email", + "type": "Handler", + "api_version": "core/v2" + } + } + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +To use pipelines, list them in check definitions in the [pipelines array][15]. +All the observability events that the check produces will be processed according to the pipeline's workflows. + +## Handlers + +[Handlers][1] are actions the Sensu backend executes on events. +Sensu also checks your handlers for the event filters and mutators to apply in the [filter][7] and [transform][8] stages. + +A few different types of handlers are available in Sensu. +The most common are [pipe handlers][4], which work similarly to [checks][2] and enable Sensu to interact with almost any computer program via [standard streams][3]. + +Here's an example resource definition for a pipe handler — read [Send Slack alerts with handlers][11] to learn how to configure your own version of this handler: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Handler +api_version: core/v2 +metadata: + name: slack +spec: + command: sensu-slack-handler --channel '#monitoring' + env_vars: + - SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T0000/B000/XXXXXXXX + runtime_assets: + - sensu-slack-handler + secrets: null + timeout: 0 + type: pipe +{{< /code >}} + +{{< code json >}} +{ + "type": "Handler", + "api_version": "core/v2", + "metadata": { + "name": "slack" + }, + "spec": { + "command": "sensu-slack-handler --channel '#monitoring'", + "env_vars": [ + "SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T0000/B000/XXXXXXXX" + ], + "runtime_assets": [ + "sensu-slack-handler" + ], + "secrets": null, + "timeout": 0, + "type": "pipe" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +Other types of handlers include [Sumo Logic metrics handlers][12] and [TCP stream handlers][13], which provide persistent connections for transmitting Sensu observation data to remote data storage services to help prevent data bottlenecks. +Sensu's Sumo Logic metrics handlers and TCP stream handlers are available for use **only** in [pipelines][14]. + +You can also use [traditional TCP/UDP handlers][5] to send your observation data to remote sockets and [handler sets][6] to streamline groups of actions to execute for certain types of events. + +Discover, download, and share Sensu handler dynamic runtime assets in [Bonsai][9], the Sensu asset hub +Read [Use assets to install plugins][10] to get started. + + +[1]: handlers/ +[2]: ../observe-schedule/checks/ +[3]: https://en.wikipedia.org/wiki/Standard_streams +[4]: handlers/#pipe-handlers +[5]: handlers/#tcpudp-handlers +[6]: handlers/#handler-sets +[7]: ../observe-filter/ +[8]: ../observe-transform/ +[9]: https://bonsai.sensu.io/ +[10]: ../../plugins/use-assets-to-install-plugins/ +[11]: send-slack-alerts/ +[12]: sumo-logic-metrics-handlers/ +[13]: tcp-stream-handlers/ +[14]: pipelines/ +[15]: ../observe-schedule/checks/#pipelines-attribute diff --git a/content/sensu-go/6.12/observability-pipeline/observe-process/aggregate-metrics-statsd.md b/content/sensu-go/6.12/observability-pipeline/observe-process/aggregate-metrics-statsd.md new file mode 100644 index 0000000000..b8deb43199 --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-process/aggregate-metrics-statsd.md @@ -0,0 +1,73 @@ +--- +title: "Aggregate metrics with the Sensu StatsD listener" +linkTitle: "Aggregate StatsD Metrics" +guide_title: "Aggregate metrics with the Sensu StatsD listener" +type: "guide" +description: "Sensu agents include a StatsD listener you can use to send application performance, CPU, I/O, and network utilization metrics to your observability pipeline." +weight: 100 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: observe-process +--- + +Sensu implements a StatsD listener on its agents. +[StatsD][1] is a daemon, tool, and protocol that you can use to send, collect, and aggregate custom metrics. + +With StatsD, you can measure anything and everything. +Collect custom metrics in your code and send them to a StatsD server to monitor applicaton performance. +Monitor CPU, I/O, and network system levels with collection daemons. +You can feed the metrics that StatsD aggregates to multiple different backends to store or visualize the data. + +Services that implement StatsD typically expose UDP port 8125 to receive metrics according to the line protocol `:|`. + +## Configure the StatsD listener + +Use configuration flags to configure the Sensu StatsD Server when you start up a Sensu agent. + +The following flags allow you to configure event handlers, flush interval, address, and port: + +{{< code text >}} +--statsd-disable disables the statsd listener and metrics server +--statsd-event-handlers stringSlice comma-delimited list of event handlers for statsd metrics +--statsd-flush-interval int number of seconds between statsd flush (default 10) +--statsd-metrics-host string address used for the statsd metrics server (default "127.0.0.1") +--statsd-metrics-port int port used for the statsd metrics server (default 8125) +{{< /code >}} + +For example: + +{{< code shell >}} +sensu-agent start --statsd-event-handlers influx-db --statsd-flush-interval 1 --statsd-metrics-host "123.4.5.6" --statsd-metrics-port 8125 +{{< /code >}} + +Each Sensu agent listens on the default port 8125 for UDP messages that follow the StatsD line protocol. +StatsD aggregates the metrics, and Sensu translates them to Sensu metrics and events that can be passed to the event pipeline. + +## Access the StatsD listener + +After you configure the StatsD listener, access it with the netcat utility command: + +{{< code shell >}} +echo 'abc.def.g:10|c' | nc -w1 -u localhost 8125 +{{< /code >}} + +Metrics received through the StatsD listener are not stored in etcd. +Instead, you must configure event handlers to send the data to a storage solution (for example, a time-series database like InfluxDB). + +## What's next + +Now that you know how to feed StatsD metrics into Sensu, check out these resources to learn how to handle the StatsD metrics: + +* [InfluxDB handler guide][3]: instructions for using Sensu's built-in metric handler +* [Handlers reference][2]: in-depth documentation for Sensu handlers +* [Pipelines reference][6]: information about the Sensu pipeline resource, which you can use to create event processing workflows with event filters, mutators, and handlers + + +[1]: https://github.com/statsd/statsd +[2]: ../handlers/ +[3]: ../populate-metrics-influxdb/ +[4]: https://nc110.sourceforge.io/ +[6]: ../pipelines/ diff --git a/content/sensu-go/6.12/observability-pipeline/observe-process/handler-templates.md b/content/sensu-go/6.12/observability-pipeline/observe-process/handler-templates.md new file mode 100644 index 0000000000..9377570c5f --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-process/handler-templates.md @@ -0,0 +1,254 @@ +--- +title: "Create handler templates" +linkTitle: "Create Handler Templates" +guide_title: "Create handler templates" +type: "guide" +description: "Add meaningful, actionable context to alerts with event-based templating for your handlers. Read this guide to learn how to create handler templates." +weight: 120 +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: observe-process +--- + +Sensu Go uses the [Go template package][1], which allows you to generate text output that includes observation data from events. +Sensu handler templates include HTML-formatted text and data derived from event attributes like `event.entity.name` and `event.check.output`. +This allows you to add meaningful, actionable context to alerts. + +For example, a template for a brief Slack alert might include information about the affected entity and its status, as well as a link to the organization's playbook for resolving observability alerts: + +{{< code html >}} + + +The entity {{.Entity.Name}} has a status of {{.Check.State}}. The entity has reported the same status for {{.Check.Occurrences}} preceding events.
    +The playbook for managing this alert is available at https://example.com/observability/alerts/playbook. + + +{{< /code >}} + +## Template syntax and format + +Handler templates use dot notation syntax to access event attributes, with the event attribute wrapped in double curly braces. +The initial dot indicates `event`. + +For example, in a handler template, a reference to the event attribute `event.check.occurrences` becomes `{{.Check.Occurrences}}`. + +Use HTML to format the text and spacing in your templates. +All text outside double curly braces is copied directly into the template output, with HTML formatting applied. + +## Available event attributes + +If you are using a plugin that supports template output, every attribute in the Sensu event is available for substitution via handler templating. +However, the attribute capitalization pattern is different for handler templates than for event format. + +The table below lists the event attributes that are available to use in handler templates, in the correct dot notation and capitalization pattern. +You can also use the [template toolkit command][11] to print available event attributes for a specific event. + +{{% notice note %}} +**NOTE**: The [entity](../../observe-entities/entities/#spec-attributes) and [events](../../observe-events/events/#spec-attributes) specifications describe each attribute in detail. +{{% /notice %}} + +| attribute | attribute | attribute | +| --- | --- | --- | +| `.HasCheck` | `.HasMetrics` | `.IsIncident` | +| `.IsResolution` | `.IsSilenced` | `.Timestamp` | +| `.Check.Annotations` | `.Check.CheckHooks` | `.Check.Command` | +| `.Check.Cron` | `.Check.DiscardOutput` | `.Check.Duration` | +| `.Check.EnvVars` | `.Check.Executed` | `.Check.ExtendedAttributes` | +| `.Check.Handlers` | `.Check.HighFlapThreshold` | `.Check.History` | +| `.Check.Hooks` | `.Check.Interval` | `.Check.Issued` | +| `.Check.Labels` | `.Check.LastOK` | `.Check.LowFlapThreshold` | +| `.Check.MaxOutputSize` | `.Check.Name` | `.Check.Namespace` | +| `.Check.Occurrences` | `.Check.OccurrencesWatermark` | `.Check.Output` | +| `.Check.OutputMetricFormat` | `.Check.OutputMetricHandlers` | `.Check.ProxyEntityName` | +| `.Check.ProxyRequests` | `.Check.Publish` | `.Check.RoundRobin` | +| `.Check.RuntimeAssets` | `.Check.Secrets` | `.Check.Silenced` | +| `.Check.State` | `.Check.Status` | `.Check.Stdin` | +| `.Check.Subdue` | `.Check.Subscriptions` | `.Check.Timeout` | +| `.Check.TotalStateChange` | `.Check.Ttl` | `.Entity.Annotations` | +| `.Entity.Deregister` | `.Entity.Deregistration` | `.Entity.EntityClass` | +| `.Entity.ExtendedAttributes` | `.Entity.KeepaliveHandlers` | `.Entity.Labels` | +| `.Entity.LastSeen` | `.Entity.Name` | `.Entity.Namespace` | +| `.Entity.Redact` | `.Entity.SensuAgentVersion` | `.Entity.Subscriptions` | +| `.Entity.System` | `.Entity.System.Arch` | `.Entity.System.ARMVersion` | +| `.Entity.System.CloudProvider` | `.Entity.System.Hostname` | `.Entity.System.LibcType` | +| `.Entity.System.Network` | `.Entity.System.OS` | `.Entity.System.Platform` | +| `.Entity.System.PlatformFamily` | `.Entity.System.PlatformVersion` | `.Entity.System.Processes` | +| `.Entity.System.VMRole` | `.Entity.System.VMSystem` | `.Entity.User` | +| `.Metrics.Handlers` | `.Metrics.Points` | | + +## Template toolkit command + +The [sensu/template-toolkit-command][8] dynamic runtime asset provides a sensuctl command plugin you can use to print a list of available event attributes in handler template dot notation syntax and validate your handler template output. + +The template toolkit command uses event data you supply via stdin in JSON format. + +Add the Sensu template toolkit command asset to Sensu: + +{{< code shell >}} +sensuctl asset add sensu/template-toolkit-command:0.4.0 -r template-toolkit-command +{{< /code >}} + +This example uses the `-r` (rename) flag to specify a shorter name for the asset: `template-toolkit-command`. + +You can also download the latest asset definition from [Bonsai][8]. + +Run `sensuctl asset list` to confirm that the asset is ready to use: + +{{< code text >}} + Name URL Hash + ────────────────────────── ───────────────────────────────────────────────────────────────────────────────────────────── ───────── + template-toolkit-command //assets.bonsai.sensu.io/.../template-toolkit-command_0.4.0_windows_amd64.tar.gz 019ccf3 + template-toolkit-command //assets.bonsai.sensu.io/.../template-toolkit-command_0.4.0_darwin_amd64.tar.gz b771813 + template-toolkit-command //assets.bonsai.sensu.io/.../template-toolkit-command_0.4.0_linux_armv7.tar.gz 4e7ad65 + template-toolkit-command //assets.bonsai.sensu.io/.../template-toolkit-command_0.4.0_linux_arm64.tar.gz 02eca1f + template-toolkit-command //assets.bonsai.sensu.io/.../template-toolkit-command_0.4.0_linux_386.tar.gz 56ed603 + template-toolkit-command //assets.bonsai.sensu.io/.../template-toolkit-command_0.4.0_linux_amd64.tar.gz 7dbd2c6 +{{< /code >}} + +### Print available event attributes + +Use the template toolkit command to print a list of the available event attributes as well as the correct dot notation and capitalization pattern for a specific event (in this example, `event.json`): + +{{< code shell >}} +cat event.json | sensuctl command exec template-toolkit-command -- --dump-names +{{< /code >}} + +The response lists the available attributes for the event: + +{{< code text >}} +INFO[0000] asset includes builds, using builds instead of asset asset=template-toolkit-command component=asset-manager entity=sensuctl +.Event{ + .Timestamp: 1580310179, + .Entity{ + .EntityClass: "agent", + .System: .System{ + [...] + .Check{ + .Command: "", + .Handlers: {"keepalive"}, + .HighFlapThreshold: 0x0, + [...] +{{< /code >}} + +In this example, the response lists the available event attributes `.Timestamp`, `.Entity.EntityClass`, `.Entity.System`, `.Check.Command`, `.Check.Handlers`, and `.Check.HighFlapThreshold`. + +You can also use `sensuctl event info ` to print the correct notation and pattern: template output for a specific event (in this example, an event for entity `server01` and check `server-health`): + +{{< code shell >}} +sensuctl event info server01 server-health --format json | sensuctl command exec template-toolkit -- --dump-names +{{< /code >}} + +The response lists the available attributes for the event: + +{{< code text >}} +INFO[0000] asset includes builds, using builds instead of asset asset=template-toolkit-command component=asset-manager entity=sensuctl +.Event{ + .Timestamp: 1580310179, + .Entity:{ + .EntityClass: "proxy", + .System: .System{ + [...] + .Check:{ + .Command: "health.sh", + .Handlers: {"slack"}, + .HighFlapThreshold: 0x0, + [...] +{{< /code >}} + +### Validate handler template output + +Use the template toolkit command to validate the dot notation syntax and output for any event attribute. + +For example, to test the output for the `{{.Check.Name}}` attribute for the event `event.json`: + +{{< code shell >}} +cat event.json | sensuctl command exec template-toolkit-command -- --template "{{.Check.Name}}" +{{< /code >}} + +The response will list the template output: + +{{< code text >}} +INFO[0000] asset includes builds, using builds instead of asset asset=template-toolkit-command component=asset-manager entity=sensuctl +executing command with --template {{.Check.Name}} +Template String Output: keepalive +{{< /code >}} + +In this example, the command validates that for the `event.json` event, the handler template will replace `{{.Check.Name}}` with `keepalive` in template output. + +You can also use `sensuctl event info ` to validate template output for a specific event (in this example, an event for entity `webserver01` and check `check-http`): + +{{< code shell >}} +sensuctl event info webserver01 check-http --format json | sensuctl command exec template-toolkit-command -- --template "Server: {{.Entity.Name}} Check: {{.Check.Name}} Status: {{.Check.State}}" +{{< /code >}} + +The response will list the template output: + +{{< code text >}} +Executing command with --template Server: {{.Entity.Name}} Check: {{.Check.Name}} Status: {{.Check.State}} +Template String Output: Server: "webserver01 Check: check-http Status: passing" +{{< /code >}} + +## Sensu Email Handler plugin + +The [sensu/sensu-email-handler][9] dynamic runtime asset allows you to provide a template for the body of the email alert. +For example, this template will produce an email body that includes the name of the check and entity associated with the event, the status and number of occurrences, and other event details: + +{{< code html >}} + + +Greetings, + +

    Informational Details

    +Check: {{.Check.Name}}
    +Entity: {{.Entity.Name}}
    +State: {{.Check.State}}
    +Occurrences: {{.Check.Occurrences}}
    +Playbook: https://example.com/monitoring/wiki/playbook +

    Check Output Details

    +Check Output: {{.Check.Output}} +

    Check Hook(s)

    +{{range .Check.Hooks}}Hook Name: {{.Name}}
    +Hook Command: {{.Command}}
    +Hook Output: {{.Output}}
    +{{end}}
    +
    +
    +#monitoringlove,
    +
    +Sensu
    + + +{{< /code >}} + +The sensu/sensu-email-handler dynamic runtime asset also includes a UnixTime function that allows you to print timestamp values from events in human-readable format. +Read the [sensu/sensu-email-handler Bonsai page][9] for details. + +## Sensu PagerDuty Handler example + +The [sensu/sensu-pagerduty-handler][10] dynamic runtime asset includes a basic template for the PagerDuty alert summary: + +{{< code shell >}} +"{{.Entity.Name}}/{{.Check.Name}} : {{.Check.Output}}" +{{< /code >}} + +With this template, the summary for every alert in PagerDuty will include: + +- The name of the affected entity. +- The name of the check that produced the event. +- The check output for the event. + +Read the [Sensu PagerDuty Handler Bonsai page][10] for details. + + +[1]: https://pkg.go.dev/text/template +[3]: ../../observe-events/events/#spec-attributes +[4]: #available-event-attributes +[5]: https://golang.org/pkg/time/#Time.Format +[6]: https://yourbasic.org/golang/format-parse-string-time-date-example/ +[7]: https://bonsai.sensu.io/ +[8]: https://bonsai.sensu.io/assets/sensu/template-toolkit-command +[9]: https://bonsai.sensu.io/assets/sensu/sensu-email-handler +[10]: https://bonsai.sensu.io/assets/sensu/sensu-pagerduty-handler +[11]: #template-toolkit-command diff --git a/content/sensu-go/6.12/observability-pipeline/observe-process/handlers.md b/content/sensu-go/6.12/observability-pipeline/observe-process/handlers.md new file mode 100644 index 0000000000..b332075a5e --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-process/handlers.md @@ -0,0 +1,951 @@ +--- +title: "Handlers reference" +linkTitle: "Handlers Reference" +reference_title: "Handlers" +type: "reference" +description: "Read this reference to learn to use handlers, the actions the Sensu backend executes on events, in your automated monitoring and observability workflows." +weight: 20 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: observe-process +--- + +Sensu executes handlers during the **[process][22]** stage of the [observability pipeline][29]. + +Handlers are actions the Sensu backend executes on events. +Several types of handlers are available. +The most common are `pipe` handlers, which work similarly to [checks][1] and enable Sensu to interact with almost any computer program via [standard streams][2]. + +- **Pipe handlers** send observation data (events) into arbitrary commands via stdin +- **TCP/UDP handlers** send observation data (events) to a remote socket +- **Handler sets** group event handlers and streamline groups of actions to execute for certain types of events (also called "set handlers") + +The handler stack concept describes a group of handlers or a handler set that escalates events through a series of different handlers. + +Discover, download, and share Sensu handler dynamic runtime assets using [Bonsai][16], the Sensu asset hub. +Read [Use dynamic runtime assets to install plugins][23] to get started. + +## Pipe handlers + +Pipe handlers are external commands that can consume [event][3] data via stdin. + +### Pipe handler example + +This example shows a pipe handler resource definition with the minimum required attributes: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Handler +api_version: core/v2 +metadata: + name: pipe_handler_minimum +spec: + command: command-example + type: pipe +{{< /code >}} + +{{< code json >}} +{ + "type": "Handler", + "api_version": "core/v2", + "metadata": { + "name": "pipe_handler_minimum" + }, + "spec": { + "command": "command-example", + "type": "pipe" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +### Pipe handler command + +Pipe handler definitions include a `command` attribute, which is a command for the Sensu backend to execute. + +#### Pipe handler command arguments + +Pipe handler `command` attributes may include command line arguments for controlling the behavior of the `command` executable. + +## TCP/UDP handlers + +TCP and UDP handlers enable Sensu to forward event data to arbitrary TCP or UDP sockets for external services to consume. + +### TCP/UDP handler example + +This handler will send event data to a TCP socket (10.0.1.99:4444) and timeout if an acknowledgement (`ACK`) is not received within 30 seconds: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Handler +api_version: core/v2 +metadata: + name: tcp_handler +spec: + socket: + host: 10.0.1.99 + port: 4444 + type: tcp + timeout: 30 +{{< /code >}} + +{{< code json >}} +{ + "type": "Handler", + "api_version": "core/v2", + "metadata": { + "name": "tcp_handler" + }, + "spec": { + "type": "tcp", + "timeout": 30, + "socket": { + "host": "10.0.1.99", + "port": 4444 + } + } +} +{{< /code >}} + +{{< /language-toggle >}} + +Change the `type` from `tcp` to `udp` to configure a UDP handler: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Handler +api_version: core/v2 +metadata: + name: udp_handler +spec: + socket: + host: 10.0.1.99 + port: 4444 + type: udp + timeout: 30 +{{< /code >}} + +{{< code json >}} +{ + "type": "Handler", + "api_version": "core/v2", + "metadata": { + "name": "udp_handler" + }, + "spec": { + "type": "udp", + "timeout": 30, + "socket": { + "host": "10.0.1.99", + "port": 4444 + } + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Handler sets + +{{% notice note %}} +**NOTE**: We recommend using [pipelines](../pipelines/) to configure multiple workflows for different handlers instead of handler sets. +{{% /notice %}} + +Handler set definitions allow you to use a single named handler set to refer to groups of handlers. +The handler set becomes a collection of individual actions to take (via each included handler) on event data. + +For example, suppose you have already created these two handlers: + +- `elasticsearch` to send all observation data to Elasticsearch. +- `opsgenie` to send non-OK status alerts to your OpsGenie notification channel. + +You can list both of these handlers in a handler set to automate and streamline your workflow, specifying `type: set`: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Handler +api_version: core/v2 +metadata: + name: send_events_notify_operator +spec: + handlers: + - elasticsearch + - opsgenie + type: set +{{< /code >}} + +{{< code json >}} +{ + "type": "Handler", + "api_version": "core/v2", + "metadata": { + "name": "send_events_notify_operator" + }, + "spec": { + "type": "set", + "handlers": [ + "elasticsearch", + "opsgenie" + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +Now you can route observation data to Elasticsearch and alerts to OpsGenie with a single handler definition, the `send_events_notify_operator` handler set. + +{{% notice note %}} +**NOTE**: Attributes defined in handler sets do not apply to the handlers they include. +For example, `filters` and `mutator` attributes defined in a handler set will have no effect on handlers. +Define these attributes in individual handlers instead, or use [pipelines](../pipelines/). +{{% /notice %}} + +## Handler stacks + +{{% notice note %}} +**NOTE**: We recommend using [pipelines](../pipelines/) to configure multiple workflows for escalating events through a series of handlers instead of handler stacks. +{{% /notice %}} + +The handler stack concept refers to a group of handlers or a handler set that escalates events through a series of different handlers. +For example, suppose you want a handler stack with three levels of escalation: + +- Level 1: On the first occurrence, attempt remediation. +- Level 2: On the fifth occurrence, send an alert to Slack. +- Level 3: On the tenth occurrence, send an alert to PagerDuty. +Continue to send this alert on every tenth occurrence thereafter until the incident is resolved. + +A handler stack for this scenario requires three handlers to take the desired actions based on three corresponding event filters that control the escalation levels: + +- Level 1 requires an event filter with the built-in [`is_incident` filter][30] plus an [occurrence-based filter][32] that uses an expression like `event.check.occurrences ==1` and a corresponding remediation handler. +- Level 2 requires an event filter with `is_incident` plus an occurrence-based filter that uses an expression like `event.check.occurrences == 5` and a corresponding Slack handler. +- Level 3 requires an event filter with `is_incident` plus an occurrence-based filter that uses an expression like `event.check.occurrences % 10 == 0` to match event data with an occurrences value that is evenly divisible by 10 via a modulo operator calculation and a corresponding PagerDuty handler. + +With these event filters and handlers configured, you can create a [handler set][31] that includes the three handlers in your stack. +You can also list the three handlers in the [handlers array][33] in your check definition instead. + +{{% notice protip %}} +**PRO TIP**: This scenario relies on six different resources, three event filters and three handlers, to describe the handler stack concept, but you can use Sensu dynamic runtime assets and integrations to achieve the same escalating alert levels in other ways.

    +For example, you can use the `is_incident` event filter in conjunction with the [sensu/sensu-go-fatigue-check-filter](https://bonsai.sensu.io/assets/sensu/sensu-go-fatigue-check-filter) asset to control event escalation. +The [sensu/sensu-ansible-handler](https://bonsai.sensu.io/assets/sensu/sensu-ansible-handler), [sensu/sensu-rundeck-handler](https://bonsai.sensu.io/assets/sensu/sensu-rundeck-handler), and [sensu/sensu-saltstack-handler](https://bonsai.sensu.io/assets/sensu/sensu-saltstack-handler) auto-remediation integrations and the [sensu/sensu-remediation-handler](https://bonsai.sensu.io/assets/sensu/sensu-remediation-handler) asset also include built-in occurrence- and severity-based event filtering. +{{% /notice %}} + +## Keepalive event handlers + +Sensu [keepalives][12] are the heartbeat mechanism used to ensure that all registered [Sensu agents][13] are operational and can reach the [Sensu backend][14]. +You can connect keepalive events to your monitoring workflows using a keepalive handler. +Sensu looks for an event handler named `keepalive` and automatically uses it to process keepalive events. + +Suppose you want to receive Slack notifications for keepalive alerts, and you already have a [Slack handler set up to process events][15]. +To process keepalive events using the Slack pipeline, create a handler set named `keepalive` and add the `slack` handler to the `handlers` array. +The resulting `keepalive` handler set configuration will look like this example: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Handler +api_version: core/v2 +metadata: + name: keepalive +spec: + handlers: + - slack + type: set +{{< /code >}} + +{{< code json >}} +{ + "type": "Handler", + "api_version": "core/v2", + "metadata": { + "name": "keepalive" + }, + "spec": { + "type": "set", + "handlers": [ + "slack" + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +You can also use the [`keepalive-handlers`][19] configuration option to send keepalive events to any handler you have configured. +If you do not specify a keepalive handler with the `keepalive-handlers` configuration option, the Sensu backend will use the default `keepalive` handler and create an event in sensuctl and the Sensu web UI. + +## Handler specification + +### Top-level attributes + +api_version | +-------------|------ +description | Top-level attribute that specifies the Sensu API group and version. For handlers in this version of Sensu, the `api_version` should always be `core/v2`. +required | Required for handler definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][4]. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +api_version: core/v2 +{{< /code >}} +{{< code json >}} +{ + "api_version": "core/v2" +} +{{< /code >}} +{{< /language-toggle >}} + +metadata | +-------------|------ +description | Top-level collection of metadata about the handler that includes `name`, `namespace`, and `created_by` as well as custom `labels` and `annotations`. The `metadata` map is always at the top level of the handler definition. This means that in `wrapped-json` and `yaml` formats, the `metadata` scope occurs outside the `spec` scope. Read [metadata attributes][8] for details. +required | Required for handler definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][4]. +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +metadata: + name: handler-slack + namespace: default + created_by: admin + labels: + region: us-west-1 + annotations: + slack-channel: "#monitoring" +{{< /code >}} +{{< code json >}} +{ + "metadata": { + "name": "handler-slack", + "namespace": "default", + "created_by": "admin", + "labels": { + "region": "us-west-1" + }, + "annotations": { + "slack-channel": "#monitoring" + } + } +} +{{< /code >}} +{{< /language-toggle >}} + +spec | +-------------|------ +description | Top-level map that includes the handler [spec attributes][5]. +required | Required for handler definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][4]. +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +spec: + type: tcp + socket: + host: 10.0.1.99 + port: 4444 + metadata: + name: tcp_handler + namespace: default +{{< /code >}} +{{< code json >}} +{ + "spec": { + "type": "tcp", + "socket": { + "host": "10.0.1.99", + "port": 4444 + }, + "metadata": { + "name": "tcp_handler", + "namespace": "default" + } + } +} +{{< /code >}} +{{< /language-toggle >}} + +type | +-------------|------ +description | Top-level attribute that specifies the [`sensuctl create`][4] resource type. Handlers should always be type `Handler`. +required | Required for handler definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][4]. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +type: Handler +{{< /code >}} +{{< code json >}} +{ + "type": "Handler" +} +{{< /code >}} +{{< /language-toggle >}} + +### Metadata attributes + +| annotations | | +-------------|------ +description | Non-identifying metadata to include with observation event data that you can access with [event filters][24]. You can use annotations to add data that's meaningful to people or external tools that interact with Sensu.

    In contrast to labels, you cannot use annotations in [API response filtering][10], [sensuctl response filtering][11], or [web UI views][28]. +required | false +type | Map of key-value pairs. Keys and values can be any valid UTF-8 string. +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +annotations: + managed-by: ops + playbook: www.example.url +{{< /code >}} +{{< code json >}} +{ + "annotations": { + "managed-by": "ops", + "playbook": "www.example.url" + } +} +{{< /code >}} +{{< /language-toggle >}} + +| created_by | | +-------------|------ +description | Username of the Sensu user who created the handler or last updated the handler. Sensu automatically populates the `created_by` field when the handler is created or updated. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +created_by: admin +{{< /code >}} +{{< code json >}} +{ + "created_by": "admin" +} +{{< /code >}} +{{< /language-toggle >}} + +| labels | | +-------------|------ +description | Custom attributes to include with observation event data that you can use for response and web UI view filtering.

    If you include labels in your event data, you can filter [API responses][10], [sensuctl responses][11], and [web UI views][25] based on them. In other words, labels allow you to create meaningful groupings for your data.

    Limit labels to metadata you need to use for response filtering. For complex, non-identifying metadata that you will *not* need to use in response filtering, use annotations rather than labels. +required | false +type | Map of key-value pairs. Keys can contain only letters, numbers, and underscores and must start with a letter. Values can be any valid UTF-8 string. +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +labels: + environment: development + region: us-west-2 +{{< /code >}} +{{< code json >}} +{ + "labels": { + "environment": "development", + "region": "us-west-2" + } +} +{{< /code >}} +{{< /language-toggle >}} + +| name | | +-------------|------ +description | Unique string used to identify the handler. Handler names cannot contain special characters or spaces (validated with Go regex [`\A[\w\.\-]+\z`][18]). Each handler must have a unique name within its namespace. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +name: handler-slack +{{< /code >}} +{{< code json >}} +{ + "name": "handler-slack" +} +{{< /code >}} +{{< /language-toggle >}} + +| namespace | | +-------------|------ +description | Sensu [RBAC namespace][9] that the handler belongs to. +required | false +type | String +default | `default` +example | {{< language-toggle >}} +{{< code yml >}} +namespace: production +{{< /code >}} +{{< code json >}} +{ + "namespace": "production" +} +{{< /code >}} +{{< /language-toggle >}} + +### Spec attributes + +command | +-------------|------ +description | Handler command to be executed. The event data is passed to the process via stdin. {{% notice note %}} +**NOTE**: The `command` attribute is only supported for pipe handlers (that is, handlers configured with `"type": "pipe"`). +{{% /notice %}} +required | true (if `type` equals `pipe`) +type | String +example | {{< language-toggle >}} +{{< code yml >}} +command: /etc/sensu/plugins/pagerduty.go +{{< /code >}} +{{< code json >}} +{ + "command": "/etc/sensu/plugins/pagerduty.go" +} +{{< /code >}} +{{< /language-toggle >}} + +env_vars | +-------------|------ +description | Array of environment variables to use with command execution. {{% notice note %}} +**NOTE**: The `env_vars` attribute is only supported for pipe handlers (that is, handlers configured with `"type": "pipe"`). +{{% /notice %}} +required | false +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +env_vars: +- API_KEY=0428d6b8nb51an4d95nbe28nf90865a66af5 +{{< /code >}} +{{< code json >}} +{ + "env_vars": [ + "API_KEY=0428d6b8nb51an4d95nbe28nf90865a66af5" + ] +} +{{< /code >}} +{{< /language-toggle >}} + +filters | +-------------|------ +description | Array of Sensu event filters (by names) to use when filtering events for the handler. Each array item must be a string.{{% notice note %}} +**NOTE**: We recommend using [pipelines](../pipelines/), which allow you to list event filters directly in the pipeline resource definition instead of in handlers.

    +Pipelines ignore any event filters specified in handler definitions, so you do not need to remove them to use your existing handlers — just make sure to define the event filters you want to use in the pipeline workflow. +{{% /notice %}} +required | false +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +filters: +- is_incident +- not_silenced +- state_change_only +{{< /code >}} +{{< code json >}} +{ + "filters": [ + "is_incident", + "not_silenced", + "state_change_only" + ] +} +{{< /code >}} +{{< /language-toggle >}} + +handlers | +-------------|------ +description | Array of Sensu event handlers (by their names) to use for events using the handler set. Each array item must be a string. {{% notice note %}} +**NOTE**: The `handlers` attribute is only supported for handler sets (that is, handlers configured with `"type": "set"`).

    +We recommend using [pipelines](../pipelines/) to configure multiple workflows instead of handler sets. +{{% /notice %}} +required | true (if `type` equals `set`) +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +handlers: +- pagerduty +- email +- ec2 +{{< /code >}} +{{< code json >}} +{ + "handlers": [ + "pagerduty", + "email", + "ec2" + ] +} +{{< /code >}} +{{< /language-toggle >}} + +mutator | +-------------|------ +description | Name of the Sensu event mutator to use to mutate event data for the handler.{{% notice note %}} +**NOTE**: We recommend using [pipelines](../pipelines/), which allow you to list mutators directly in the pipeline resource definition instead of in handlers.

    +Pipelines ignore any mutators specified in handler definitions, so you do not need to remove them to use your existing handlers — just make sure to define the mutator you want to use in the pipeline workflow. +{{% /notice %}} +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +mutator: only_check_output +{{< /code >}} +{{< code json >}} +{ + "mutator": "only_check_output" +} +{{< /code >}} +{{< /language-toggle >}} + +runtime_assets | +---------------|------ +description | Array of [Sensu dynamic runtime assets][7] (by names) required at runtime to execute the `command` +required | false +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +runtime_assets: +- metric-handler +{{< /code >}} +{{< code json >}} +{ + "runtime_assets": [ + "metric-handler" + ] +} +{{< /code >}} +{{< /language-toggle >}} + +secrets | +---------------|------ +description | Array of the name/secret pairs to use with command execution. +required | false +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +secrets: +- name: ANSIBLE_HOST + secret: sensu-ansible-host +- name: ANSIBLE_TOKEN + secret: sensu-ansible-token +{{< /code >}} +{{< code json >}} +{ + "secrets": [ + { + "name": "ANSIBLE_HOST", + "secret": "sensu-ansible-host" + }, + { + "name": "ANSIBLE_TOKEN", + "secret": "sensu-ansible-token" + } + ] +} +{{< /code >}} +{{< /language-toggle >}} + +socket | +-------------|------ +description | Scope for [`socket` definition][6] used to configure the TCP/UDP handler socket. {{% notice note %}} +**NOTE**: The `socket` attribute is only supported for TCP/UDP handlers (that is, handlers configured with `"type": "tcp"` or `"type": "udp"`). +{{% /notice %}} +required | true (if `type` equals `tcp` or `udp`) +type | Hash +example | {{< language-toggle >}} +{{< code yml >}} +socket: {} +{{< /code >}} +{{< code json >}} +{ + "socket": {} +} +{{< /code >}} +{{< /language-toggle >}} + +timeout | +------------|------ +description | Handler execution duration timeout (hard stop). In seconds. Only used by `pipe`, `tcp`, and `udp` handler types. +required | false +type | Integer +default | `60` (for `tcp` and `udp` handlers) +example | {{< language-toggle >}} +{{< code yml >}} +timeout: 30 +{{< /code >}} +{{< code json >}} +{ + "timeout": 30 +} +{{< /code >}} +{{< /language-toggle >}} + +type | +-------------|------ +description | Handler type. +required | true +type | String +allowed values | `pipe`, `tcp`, `udp`, and `set` +example | {{< language-toggle >}} +{{< code yml >}} +type: pipe +{{< /code >}} +{{< code json >}} +{ + "type": "pipe" +} +{{< /code >}} +{{< /language-toggle >}} + +#### `socket` attributes + +host | +-------------|------ +description | Socket host address (IP or hostname) to connect to. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +host: 8.8.8.8 +{{< /code >}} +{{< code json >}} +{ + "host": "8.8.8.8" +} +{{< /code >}} +{{< /language-toggle >}} + +port | +-------------|------ +description | Socket port to connect to. +required | true +type | Integer +example | {{< language-toggle >}} +{{< code yml >}} +port: 4242 +{{< /code >}} +{{< code json >}} +{ + "port": 4242 +} +{{< /code >}} +{{< /language-toggle >}} + +#### `secrets` attributes + +name | +-------------|------ +description | Name of the [secret][20] defined in the executable command. Becomes the environment variable presented to the handler. Read [Use secrets management in Sensu][26] for more information. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +name: ANSIBLE_HOST +{{< /code >}} +{{< code json >}} +{ + "name": "ANSIBLE_HOST" +} +{{< /code >}} +{{< /language-toggle >}} + +secret | +-------------|------ +description | Name of the Sensu secret resource that defines how to retrieve the [secret][20]. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +secret: sensu-ansible-host +{{< /code >}} +{{< code json >}} +{ + "secret": "sensu-ansible-host" +} +{{< /code >}} +{{< /language-toggle >}} + +## Send Slack alerts + +This handler will send alerts to a channel named `monitoring` with the configured webhook URL, using the `handler-slack` executable command. +The handler uses the [sensu/sensu-slack-handler][34] dynamic runtime asset. +Read [Send Slack alerts with handlers][35] for detailed instructions for adding the required asset and configuring this handler. + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Handler +api_version: core/v2 +metadata: + name: slack +spec: + command: sensu-slack-handler --channel '#monitoring' + env_vars: + - SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX + handlers: [] + runtime_assets: + - sensu/sensu-slack-handler + timeout: 0 + type: pipe +{{< /code >}} + +{{< code json >}} +{ + "type": "Handler", + "api_version": "core/v2", + "metadata": { + "name": "slack" + }, + "spec": { + "command": "sensu-slack-handler --channel '#monitoring'", + "env_vars": [ + "SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX" + ], + "handlers": [], + "runtime_assets": [ + "sensu/sensu-slack-handler" + ], + "timeout": 0, + "type": "pipe" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Send registration events + +If you configure a Sensu event handler named `registration`, the Sensu backend will create and process an event for the agent registration, apply any configured filters and mutators, and execute the registration handler. + +Read [Automatically register and deregister entities][37] for more information and a registration handler example. + +## Execute multiple handlers (handler set) + +{{% notice note %}} +**NOTE**: We recommend using [pipelines](../pipelines/) to configure multiple workflows for different handlers instead of handler sets. +{{% /notice %}} + +The following example creates a handler set, `notify_all_the_things`, that will execute three handlers: `slack`, `tcp_handler`, and `udp_handler`. + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Handler +api_version: core/v2 +metadata: + name: notify_all_the_things +spec: + handlers: + - slack + - tcp_handler + - udp_handler + type: set +{{< /code >}} + +{{< code json >}} +{ + "type": "Handler", + "api_version": "core/v2", + "metadata": { + "name": "notify_all_the_things" + }, + "spec": { + "type": "set", + "handlers": [ + "slack", + "tcp_handler", + "udp_handler" + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Use secrets management in a handler + +Learn more about [secrets management][26] for your Sensu configuration in the [secrets][20] and [secrets providers][21] references. + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Handler +api_version: core/v2 +metadata: + name: ansible-tower +spec: + type: pipe + command: sensu-ansible-handler -h $ANSIBLE_HOST -t $ANSIBLE_TOKEN + secrets: + - name: ANSIBLE_HOST + secret: sensu-ansible-host + - name: ANSIBLE_TOKEN + secret: sensu-ansible-token +{{< /code >}} + +{{< code json >}} +{ + "type": "Handler", + "api_version": "core/v2", + "metadata": { + "name": "ansible-tower" + }, + "spec": { + "type": "pipe", + "command": "sensu-ansible-handler -h $ANSIBLE_HOST -t $ANSIBLE_TOKEN", + "secrets": [ + { + "name": "ANSIBLE_HOST", + "secret": "sensu-ansible-host" + }, + { + "name": "ANSIBLE_TOKEN", + "secret": "sensu-ansible-token" + } + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + + +[1]: ../../observe-schedule/checks/ +[2]: https://en.wikipedia.org/wiki/Standard_streams +[3]: ../../observe-events/events/ +[4]: ../../../sensuctl/create-manage-resources/#create-resources +[5]: #spec-attributes +[6]: #socket-attributes +[7]: ../../../plugins/assets/ +[8]: #metadata-attributes +[9]: ../../../operations/control-access/namespaces/ +[10]: ../../../api/#response-filtering +[11]: ../../../sensuctl/filter-responses/ +[12]: ../../observe-schedule/agent#keepalive-monitoring +[13]: ../../observe-schedule/agent/ +[14]: ../../observe-schedule/backend/ +[15]: ../send-slack-alerts/ +[16]: https://bonsai.sensu.io/ +[17]: https://bonsai.sensu.io/assets/sensu/sensu-servicenow-handler/ +[18]: https://regex101.com/r/zo9mQU/2 +[19]: ../../observe-schedule/agent/#keepalive-handlers-option +[20]: ../../../operations/manage-secrets/secrets/ +[21]: ../../../operations/manage-secrets/secrets-providers/ +[22]: ../ +[23]: ../../../plugins/use-assets-to-install-plugins/ +[24]: ../../observe-filter/filters/ +[25]: ../../../web-ui/search#search-for-labels +[26]: ../../../operations/manage-secrets/secrets-management/ +[27]: ../../observe-schedule/agent/#registration-endpoint-management-and-service-discovery +[28]: ../../../web-ui/search/ +[29]: ../../../observability-pipeline/ +[30]: ../../observe-filter/filters/#built-in-filter-is_incident +[31]: #handler-sets +[32]: ../../observe-filter/filters/#filter-for-repeated-events +[33]: ../../observe-schedule/checks/#handlers-array +[34]: https://bonsai.sensu.io/assets/sensu/sensu-slack-handler +[35]: ../../observe-process/send-slack-alerts/ +[36]: ../../../plugins/featured-integrations/servicenow/ +[37]: ../../observe-entities/auto-register-deregister/ diff --git a/content/sensu-go/6.12/observability-pipeline/observe-process/pipelines.md b/content/sensu-go/6.12/observability-pipeline/observe-process/pipelines.md new file mode 100644 index 0000000000..9083d9c077 --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-process/pipelines.md @@ -0,0 +1,893 @@ +--- +title: "Pipelines reference" +linkTitle: "Pipelines Reference" +reference_title: "Pipelines" +type: "reference" +description: "Pipelines are observation event processing workflows made up of filters, mutators, and handlers. Read the reference doc to learn about pipelines." +weight: 40 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: observe-process +--- + +{{% notice warning %}} +**IMPORTANT**: The pipelines described on this page are different from the resources you can create and manage with the [`enterprise/pipeline/v1`](../../../api/enterprise/pipeline/) API. +The [`enterprise/pipeline/v1`](../../../api/enterprise/pipeline/) API allows you to create and manage resources that can **only** be used in pipelines rather than pipelines themselves.

    +Read the [Sumo Logic metrics handlers reference](../sumo-logic-metrics-handlers) and [TCP stream handlers reference](../tcp-stream-handlers) for more information about enterprise pipeline resources. +{{% /notice %}} + +Sensu executes pipelines during the **[process][22]** stage of the [observability pipeline][29]. + +Pipelines are Sensu resources composed of observation event processing [workflows][3] made up of filters, mutators, and handlers. +Instead of specifying filters and mutators in handler definitions, you can specify all three in a single pipeline workflow. + +To use a pipeline, list it in a check definition's [pipelines array][19]. +All the observability events that the check produces will be processed according to the pipeline's workflows. + +Pipelines can replace [handler sets][1] and [handler stacks][2]. +We recommend migrating your existing handler sets and stacks to pipeline workflows. + +{{% notice note %}} +**NOTE**: To use pipelines, [upgrade](../../../operations/maintain-sensu/upgrade/#upgrade-to-sensu-go-650-from-any-previous-version) your agents to Sensu Go 6.5.0. +{{% /notice %}} + +## Pipeline example + +This example shows a pipeline resource definition that includes event filters, a mutator, and a handler: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Pipeline +api_version: core/v2 +metadata: + name: incident_alerts +spec: + workflows: + - name: labeled_email_alerts + filters: + - name: is_incident + type: EventFilter + api_version: core/v2 + - name: not_silenced + type: EventFilter + api_version: core/v2 + - name: state_change_only + type: EventFilter + api_version: core/v2 + mutator: + name: add_labels + type: Mutator + api_version: core/v2 + handler: + name: email + type: Handler + api_version: core/v2 +{{< /code >}} + +{{< code json >}} +{ + "type": "Pipeline", + "api_version": "core/v2", + "metadata": { + "name": "incident_alerts" + }, + "spec": { + "workflows": [ + { + "name": "labeled_email_alerts", + "filters": [ + { + "name": "is_incident", + "type": "EventFilter", + "api_version": "core/v2" + }, + { + "name": "not_silenced", + "type": "EventFilter", + "api_version": "core/v2" + }, + { + "name": "state_change_only", + "type": "EventFilter", + "api_version": "core/v2" + } + ], + "mutator": { + "name": "add_labels", + "type": "Mutator", + "api_version": "core/v2" + }, + "handler": { + "name": "email", + "type": "Handler", + "api_version": "core/v2" + } + } + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +To use this pipeline in a check, list it in the check's [pipelines array][19]. +For example: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: incident_pipelines +spec: + command: collect.sh + interval: 10 + publish: true + subscriptions: + - system + pipelines: + - type: Pipeline + api_version: core/v2 + name: incident_alerts +{{< /code >}} + +{{< code json >}} +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "incident_pipelines" + }, + "spec": { + "command": "collect.sh", + "interval": 10, + "publish": true, + "subscriptions": [ + "system" + ], + "pipelines": [ + { + "type": "Pipeline", + "api_version": "core/v2", + "name": "incident_alerts" + } + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Workflows + +The workflows attribute is an array of event processing workflows that Sensu will apply for events produced by any check that references the pipeline. + +Workflows do not have to include an event filter or mutator, but they must specify at least one handler. + +Workflows can include more than one event filter. +If a workflow has more than one filter, Sensu applies the filters in a series, starting with the filter that is listed first. + +You can use your existing event filters, mutators, and handlers in pipeline workflows. +Pipelines ignore any filters and mutators specified in handler definitions, so you do not need to remove them to use your existing handlers — just make sure to define the event filters and mutators you want to use in the pipeline workflow. + +### Pipelines with multiple workflows + +Pipelines can include more than one workflow. + +In this example, the pipeline includes `labeled_email_alerts` and `slack_alerts` workflows: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Pipeline +api_version: core/v2 +metadata: + name: incident_alerts +spec: + workflows: + - name: labeled_email_alerts + filters: + - name: is_incident + type: EventFilter + api_version: core/v2 + - name: not_silenced + type: EventFilter + api_version: core/v2 + - name: state_change_only + type: EventFilter + api_version: core/v2 + mutator: + name: add_labels + type: Mutator + api_version: core/v2 + handler: + name: email + type: Handler + api_version: core/v2 + - name: slack_alerts + filters: + - name: is_incident + type: EventFilter + api_version: core/v2 + - name: not_silenced + type: EventFilter + api_version: core/v2 + - name: state_change_only + type: EventFilter + api_version: core/v2 + handler: + name: slack + type: Handler + api_version: core/v2 +{{< /code >}} + +{{< code json >}} +{ + "type": "Pipeline", + "api_version": "core/v2", + "metadata": { + "name": "incident_alerts" + }, + "spec": { + "workflows": [ + { + "name": "labeled_email_alerts", + "filters": [ + { + "name": "is_incident", + "type": "EventFilter", + "api_version": "core/v2" + }, + { + "name": "not_silenced", + "type": "EventFilter", + "api_version": "core/v2" + }, + { + "name": "state_change_only", + "type": "EventFilter", + "api_version": "core/v2" + } + ], + "mutator": { + "name": "add_labels", + "type": "Mutator", + "api_version": "core/v2" + }, + "handler": { + "name": "email", + "type": "Handler", + "api_version": "core/v2" + } + }, + { + "name": "slack_alerts", + "filters": [ + { + "name": "is_incident", + "type": "EventFilter", + "api_version": "core/v2" + }, + { + "name": "not_silenced", + "type": "EventFilter", + "api_version": "core/v2" + }, + { + "name": "state_change_only", + "type": "EventFilter", + "api_version": "core/v2" + } + ], + "handler": { + "name": "slack", + "type": "Handler", + "api_version": "core/v2" + } + } + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +All events from checks that specify this pipeline will be processed with both workflows, in series, starting with the workflow that is listed first in the resource definition. + +Read [Route alerts with event filters][30] for another pipeline example that includes multiple workflows for contact-based routing. + +## Pipeline specification + +### Top-level attributes + +api_version | +-------------|------ +description | Top-level attribute that specifies the Sensu API group and version. For pipelines in this version of Sensu, the api_version should always be `core/v2`. +required | Required for pipeline definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][4]. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +api_version: core/v2 +{{< /code >}} +{{< code json >}} +{ + "api_version": "core/v2" +} +{{< /code >}} +{{< /language-toggle >}} + +metadata | +-------------|------ +description | Top-level collection of metadata about the pipeline that includes `name`, `namespace`, and `created_by` as well as custom `labels` and `annotations`. The `metadata` map is always at the top level of the pipeline definition. This means that in `wrapped-json` and `yaml` formats, the `metadata` scope occurs outside the `spec` scope. Read [metadata attributes][8] for details. +required | Required for pipeline definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][4]. +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +metadata: + name: incident_alerts + namespace: default + created_by: admin + labels: + region: us-west-1 + annotations: + slack-channel: "#incidents" +{{< /code >}} +{{< code json >}} +{ + "metadata": { + "name": "incident_alerts", + "namespace": "default", + "created_by": "admin", + "labels": { + "region": "us-west-1" + }, + "annotations": { + "slack-channel": "#incidents" + } + } +} +{{< /code >}} +{{< /language-toggle >}} + +spec | +-------------|------ +description | Top-level map that includes the pipeline [spec attributes][5]. +required | Required for pipeline definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][4]. +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +spec: + workflows: + - name: labeled_email_alerts + filters: + - name: is_incident + type: EventFilter + api_version: core/v2 + - name: not_silenced + type: EventFilter + api_version: core/v2 + - name: state_change_only + type: EventFilter + api_version: core/v2 + mutator: + name: add_labels + type: Mutator + api_version: core/v2 + handler: + name: email + type: Handler + api_version: core/v2 +{{< /code >}} +{{< code json >}} +{ + "spec": { + "workflows": [ + { + "name": "labeled_email_alerts", + "filters": [ + { + "name": "is_incident", + "type": "EventFilter", + "api_version": "core/v2" + }, + { + "name": "not_silenced", + "type": "EventFilter", + "api_version": "core/v2" + }, + { + "name": "state_change_only", + "type": "EventFilter", + "api_version": "core/v2" + } + ], + "mutator": { + "name": "add_labels", + "type": "Mutator", + "api_version": "core/v2" + }, + "handler": { + "name": "email", + "type": "Handler", + "api_version": "core/v2" + } + } + ] + } +} +{{< /code >}} +{{< /language-toggle >}} + +type | +-------------|------ +description | Top-level attribute that specifies the [`sensuctl create`][4] resource type. Pipelines should always be type `Pipeline`. +required | Required for pipeline definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][4]. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +type: Pipeline +{{< /code >}} +{{< code json >}} +{ + "type": "Pipeline" +} +{{< /code >}} +{{< /language-toggle >}} + +### Metadata attributes + +| annotations | | +-------------|------ +description | Non-identifying metadata to include with observation event data that you can access with [event filters][24]. You can use annotations to add data that's meaningful to people or external tools that interact with Sensu.

    In contrast to labels, you cannot use annotations in [API response filtering][10], [sensuctl response filtering][11], or [web UI views][28]. +required | false +type | Map of key-value pairs. Keys and values can be any valid UTF-8 string. +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +annotations: + managed-by: ops + slack-channel: "#incidents" +{{< /code >}} +{{< code json >}} +{ + "annotations": { + "managed-by": "ops", + "slack-channel": "#incidents" + } +} +{{< /code >}} +{{< /language-toggle >}} + +| created_by | | +-------------|------ +description | Username of the Sensu user who created the pipeline or last updated the handler. Sensu automatically populates the `created_by` field when the pipeline is created or updated. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +created_by: admin +{{< /code >}} +{{< code json >}} +{ + "created_by": "admin" +} +{{< /code >}} +{{< /language-toggle >}} + +| labels | | +-------------|------ +description | Custom attributes to include with observation event data that you can use for response and web UI view filtering.

    If you include labels in your event data, you can filter [API responses][10], [sensuctl responses][11], and [web UI views][25] based on them. In other words, labels allow you to create meaningful groupings for your data.

    Limit labels to metadata you need to use for response filtering. For complex, non-identifying metadata that you will *not* need to use in response filtering, use annotations rather than labels. +required | false +type | Map of key-value pairs. Keys can contain only letters, numbers, and underscores and must start with a letter. Values can be any valid UTF-8 string. +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +labels: + environment: production + region: us-west-1 +{{< /code >}} +{{< code json >}} +{ + "labels": { + "environment": "production", + "region": "us-west-1" + } +} +{{< /code >}} +{{< /language-toggle >}} + +| name | | +-------------|------ +description | Unique string used to identify the pipeline. Pipeline names cannot contain special characters or spaces (validated with Go regex [`\A[\w\.\-]+\z`][18]). Each pipeline must have a unique name within its namespace. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +name: incident_alerts +{{< /code >}} +{{< code json >}} +{ + "name": "incident_alerts" +} +{{< /code >}} +{{< /language-toggle >}} + +| namespace | | +-------------|------ +description | Sensu [RBAC namespace][9] that the pipeline belongs to. +required | false +type | String +default | `default` +example | {{< language-toggle >}} +{{< code yml >}} +namespace: default +{{< /code >}} +{{< code json >}} +{ + "namespace": "default" +} +{{< /code >}} +{{< /language-toggle >}} + +### Spec attributes + +workflows | +-------------|------ +description | Array of workflows (by names) to use when filtering, mutating, and handling observability events with a pipeline. Each array item must be a string. Read [workflows attributes][6] for details. +required | false +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +workflows: + - name: labeled_email_alerts + filters: + - name: is_incident + type: EventFilter + api_version: core/v2 + - name: not_silenced + type: EventFilter + api_version: core/v2 + - name: state_change_only + type: EventFilter + api_version: core/v2 + mutator: + name: add_labels + type: Mutator + api_version: core/v2 + handler: + name: email + type: Handler + api_version: core/v2 +{{< /code >}} +{{< code json >}} +{ + "workflows": [ + { + "name": "labeled_email_alerts", + "filters": [ + { + "name": "is_incident", + "type": "EventFilter", + "api_version": "core/v2" + }, + { + "name": "not_silenced", + "type": "EventFilter", + "api_version": "core/v2" + }, + { + "name": "state_change_only", + "type": "EventFilter", + "api_version": "core/v2" + } + ], + "mutator": { + "name": "add_labels", + "type": "Mutator", + "api_version": "core/v2" + }, + "handler": { + "name": "email", + "type": "Handler", + "api_version": "core/v2" + } + } + ] +} +{{< /code >}} +{{< /language-toggle >}} + +#### Workflows attributes + +filters | +-------------|------ +description | Reference for the Sensu event filters to use when filtering events for the pipeline. Each pipeline workflow can reference more than one event filter. If a workflow has more than one filter, Sensu applies the filters in a series, starting with the filter that is listed first. Read [filters attributes][7] for details. +required | false +type | Map of key-value pairs +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +filters: +- name: is_incident + type: EventFilter + api_version: core/v2 +- name: not_silenced + type: EventFilter + api_version: core/v2 +- name: state_change_only + type: EventFilter + api_version: core/v2 +{{< /code >}} +{{< code json >}} +{ + "filters": [ + { + "name": "is_incident", + "type": "EventFilter", + "api_version": "core/v2" + }, + { + "name": "not_silenced", + "type": "EventFilter", + "api_version": "core/v2" + }, + { + "name": "state_change_only", + "type": "EventFilter", + "api_version": "core/v2" + } + ] +} +{{< /code >}} +{{< /language-toggle >}} + + + +handler | +-------------|------ +description | Reference for the Sensu handler to use for event processing in the workflow. Each pipeline workflow must reference one handler. Pipelines ignore any filters and mutators specified in handler definitions. Read [handler attributes][12] for details. +required | true +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +handler: + name: email + type: Handler + api_version: core/v2 +{{< /code >}} +{{< code json >}} +{ + "handler": { + "name": "email", + "type": "Handler", + "api_version": "core/v2" + } +} +{{< /code >}} +{{< /language-toggle >}} + +mutator | +-------------|------ +description | Reference for the Sensu mutator to use to mutate event data for the workflow. Each pipeline workflow can reference only one mutator. Read [mutator attributes][9] for details. +required | false +type | Map of key-value pairs +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +mutator: + name: add_labels + type: Mutator + api_version: core/v2 +{{< /code >}} +{{< code json >}} +{ + "mutator": { + "name": "add_labels", + "type": "Mutator", + "api_version": "core/v2" + } +} +{{< /code >}} +{{< /language-toggle >}} + +#### Filters attributes + +api_version | +-------------|------ +description | The Sensu API group and version for the event filter. For event filters in this version of Sensu, the api_version should always be `core/v2`. +required | true +type | String +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +api_version: core/v2 +{{< /code >}} +{{< code json >}} +{ + "api_version": "core/v2" +} +{{< /code >}} +{{< /language-toggle >}} + +name | +-------------|------ +description | Name of the Sensu [event filter][24] to use for the workflow. You can use the [built-in event filters][31], as well as your existing event filters, in pipeline workflows. +required | true +type | String +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +name: is_incident +{{< /code >}} +{{< code json >}} +{ + "name": "is_incident" +} +{{< /code >}} +{{< /language-toggle >}} + +type | +-------------|------ +description | The [`sensuctl create`][4] resource type for the event filter. Event filters should always be type `EventFilter`. +required | true +type | String +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +type: EventFilter +{{< /code >}} +{{< code json >}} +{ + "type": "EventFilter" +} +{{< /code >}} +{{< /language-toggle >}} + +#### Handler attributes + +api_version | +-------------|------ +description | The Sensu API group and version for the handler. +required | true +type | String +allowed values | `core/v2` for a [pipe handler][15], [TCP or UDP handler][16], or [handler set][1]

    `pipeline/v1` for a [TCP stream handler][20] or [Sumo Logic metrics handler][21] +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +api_version: core/v2 +{{< /code >}} +{{< code json >}} +{ + "api_version": "core/v2" +} +{{< /code >}} +{{< /language-toggle >}} + +name | +-------------|------ +description | Name of the Sensu [handler][13] to use for the workflow. You can use your existing handlers in pipeline workflows — pipelines ignore any filters and mutators specified in handler definitions. +required | true +type | String +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +name: email +{{< /code >}} +{{< code json >}} +{ + "name": "email" +} +{{< /code >}} +{{< /language-toggle >}} + +type | +-------------|------ +description | The [`sensuctl create`][4] resource type for the handler. +required | true +type | String +allowed values | `Handler` for a [pipe handler][15], [TCP or UDP handler][16], or [handler set][1]

    `TCPStreamHandler` for a [TCP stream handler][20]

    `SumoLogicMetricsHandler` for a [Sumo Logic metrics handler][21] +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +type: Handler +{{< /code >}} +{{< code json >}} +{ + "type": "Handler" +} +{{< /code >}} +{{< /language-toggle >}} + +#### Mutator attributes + +api_version | +-------------|------ +description | The Sensu API group and version for the mutator. For mutators in this version of Sensu, the api_version should always be `core/v2`. +required | true +type | String +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +api_version: core/v2 +{{< /code >}} +{{< code json >}} +{ + "api_version": "core/v2" +} +{{< /code >}} +{{< /language-toggle >}} + +name | +-------------|------ +description | Name of the Sensu [mutator][14] to use for the workflow. You can use your existing mutators in pipeline workflows. +required | true +type | String +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +name: add_labels +{{< /code >}} +{{< code json >}} +{ + "name": "add_labels" +} +{{< /code >}} +{{< /language-toggle >}} + +type | +-------------|------ +description | The [`sensuctl create`][4] resource type for the mutator. Mutators should always be type `Mutator`. +required | true +type | String +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +type: Mutator +{{< /code >}} +{{< code json >}} +{ + "type": "Mutator" +} +{{< /code >}} +{{< /language-toggle >}} + + +[1]: ../handlers/#handler-sets +[2]: ../handlers/#handler-stacks +[3]: #workflows +[4]: ../../../sensuctl/create-manage-resources/#create-resources +[5]: #spec-attributes +[6]: #workflows-attributes +[7]: #filters-attributes +[8]: #metadata-attributes +[9]: ../../../operations/control-access/namespaces/ +[10]: ../../../api/#response-filtering +[11]: ../../../sensuctl/filter-responses/ +[12]: #handler-attributes +[13]: ../handlers/ +[14]: ../../observe-transform/mutators/ +[15]: ../handlers/#pipe-handlers +[16]: ../handlers/#tcpudp-handlers +[17]: ../tcp-stream-handlers +[18]: https://regex101.com/r/zo9mQU/2 +[19]: ../../observe-schedule/checks/#pipelines-attribute +[20]: ../tcp-stream-handlers/ +[21]: ../sumo-logic-metrics-handlers/ +[22]: ../ +[23]: ../../../operations/maintain-sensu/upgrade/#upgrade-to-sensu-go-650-from-any-previous-version +[24]: ../../observe-filter/filters/ +[25]: ../../../web-ui/search#search-for-labels +[26]: ../../../operations/manage-secrets/secrets-management/ +[27]: ../../observe-schedule/agent/#registration-endpoint-management-and-service-discovery +[28]: ../../../web-ui/search/ +[29]: ../../../observability-pipeline/ +[30]: ../../observe-filter/route-alerts/#configure-contact-routing-with-a-pipeline +[31]: ../../observe-filter/filters/#built-in-event-filters diff --git a/content/sensu-go/6.12/observability-pipeline/observe-process/plan-maintenance.md b/content/sensu-go/6.12/observability-pipeline/observe-process/plan-maintenance.md new file mode 100644 index 0000000000..ec004fd54e --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-process/plan-maintenance.md @@ -0,0 +1,289 @@ +--- +title: "Plan maintenance windows with silencing" +linkTitle: "Plan Maintenance Windows" +guide_title: "Plan maintenance windows with silencing" +type: "guide" +description: "Use Sensu's silencing feature to suppress event handling during system maintenance so you can coordinate and perform maintenance without getting alerts." +weight: 140 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: observe-process +--- + +As the Sensu backend processes check results, the server executes [handlers][1] to send alerts or otherwise relay observation events and metrics data to external services. +Sensu’s built-in [silencing][7] capability allows you to suppress event handler execution as needed. +This feature is useful when you're planning maintenance. + +You can configure silences to prevent handlers from taking actions based on check name, entity subscription, entity name, or a combination of these factors. +In this guide, you'll create a silenced entry for a specific entity and its associated check to prevent alerts and create a time window for maintenance. + +## Requirements + +To follow this guide, install the Sensu [backend][10], make sure at least one Sensu [agent][21] is running, and configure [sensuctl][22] to connect to the backend as the [`admin` user][23]. + +{{% notice note %}} +**NOTE**: If you already have an entity and running check to use as the silencing target, skip ahead to [Create the silenced entry](#create-the-silenced-entry). +{{% /notice %}} + +## Configure a Sensu entity + +Before you create a check, you'll need a Sensu entity with the subscription `website` to run the check. +Use sensuctl to add the `website` subscription to an entity the Sensu agent is observing. + +{{% notice note %}} +**NOTE**: To find your entity name, run `sensuctl entity list`. +The `ID` is the name of your entity. +{{% /notice %}} + +Before you run the following code, replace `` with the name of the entity on your system. + +{{< code shell >}} +sensuctl entity update +{{< /code >}} + +- For `Entity Class`, press enter. +- For `Subscriptions`, type `website` and press enter. + +Before you continue, confirm both Sensu services are running: + +{{< code shell >}} +systemctl status sensu-backend && systemctl status sensu-agent +{{< /code >}} + +The response should indicate `active (running)` for both the Sensu backend and agent. + +## Register the http-checks dynamic runtime asset + +To power the check in your silenced entry, you'll use the sensu/http-checks dynamic runtime asset. +This community-tier asset includes `http-check`, the http status check command that your check will rely on. + +Register the sensu/http-checks dynamic runtime asset: + +{{< code shell >}} +sensuctl asset add sensu/http-checks:0.5.0 -r http-checks +{{< /code >}} + +This example uses the `-r` (rename) flag to specify a shorter name for the dynamic runtime asset: `http-checks`. +The response will indicate that the asset was added. + +Use sensuctl to confirm that the dynamic runtime asset is ready to use: + +{{< code shell >}} +sensuctl asset list +{{< /code >}} + +The response should list the sensu/http-checks dynamic runtime asset (renamed to `http-checks`): + +{{< code text >}} + Name URL Hash +────────────── ───────────────────────────────────────────────────────────────────── ────────── + http-checks //assets.bonsai.sensu.io/.../http-checks_0.5.0_windows_amd64.tar.gz 52ae075 + http-checks //assets.bonsai.sensu.io/.../http-checks_0.5.0_darwin_amd64.tar.gz 72d0f15 + http-checks //assets.bonsai.sensu.io/.../http-checks_0.5.0_linux_armv7.tar.gz ef18587 + http-checks //assets.bonsai.sensu.io/.../http-checks_0.5.0_linux_arm64.tar.gz 3504ddf + http-checks //assets.bonsai.sensu.io/.../http-checks_0.5.0_linux_386.tar.gz 60b8883 + http-checks //assets.bonsai.sensu.io/.../http-checks_0.5.0_linux_amd64.tar.gz 1db73a8 +{{< /code >}} + +{{% notice note %}} +**NOTE**: Sensu does not download and install dynamic runtime asset builds onto the system until they are needed for command execution. +{{% /notice %}} + +## Create the check + +With the dynamic runtime asset registered, you can create a check named `check-website` to run the command `http-check --url https://sensu.io`, at an interval of 15 seconds, for all agents subscribed to the `website` subscription, using the `sensu-site` proxy entity name. + +To add the check, run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +cat << EOF | sensuctl create +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: check-website +spec: + command: http-check --url https://sensu.io + interval: 15 + proxy_entity_name: sensu-site + publish: true + round_robin: true + runtime_assets: + - http-checks + subscriptions: + - website +EOF +{{< /code >}} + +{{< code shell "JSON" >}} +cat << EOF | sensuctl create +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "check-website" + }, + "spec": { + "command": "http-check --url https://sensu.io", + "interval": 15, + "proxy_entity_name": "sensu-site", + "publish": true, + "round_robin": true, + "runtime_assets": [ + "http-checks" + ], + "subscriptions": [ + "website" + ] + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + +Use sensuctl to confirm that Sensu added the check: + +{{< code shell >}} +sensuctl check list +{{< /code >}} + +The response should list `check-sensu-site`: + +{{< code text >}} + Name Command Interval Cron Timeout TTL Subscriptions Handlers Assets Hooks Publish? Stdin? Metric Format Metric Handlers +──────────────── ─────────────────────────────────── ────────── ────── ───────── ───── ─────────────── ────────── ───────────── ─────── ────────── ──────── ─────────────── ────────────────── + check-website http-check --url https://sensu.io 15 0 0 website http-checks true false +{{< /code >}} + +## Create the silenced entry + +The silenced entry will silence the check `check-http` on the entity `sensu-site` for a planned maintenance window that: +- Starts at **04:00** UTC on **March 14, 2022** +- Automatically ends **1 hour** later +- Adds your username as the **creator** of the silenced entry + +To create the silenced entry, run: + +{{< code shell >}} +sensuctl silenced create \ +--subscription 'entity:sensu-site' \ +--check 'check-http' \ +--begin '2022-03-14 04:00:00 -00:00' \ +--expire 3600 \ +--reason 'Planned site maintenance' +{{< /code >}} + +Use sensuctl to verify that the silenced entry against the entity `sensu-site` was created properly: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl silenced info 'entity:sensu-site:check-http' --format yaml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl silenced info 'entity:sensu-site:check-http' --format wrapped-json +{{< /code >}} + +{{< /language-toggle >}} + +The response will list the silenced resource definition, similar to the following: + +{{< language-toggle >}} + +{{< code yml >}} +type: Silenced +api_version: core/v2 +metadata: + name: entity:sensu-site:check-http +spec: + begin: 1647230400 + check: check-http + creator: admin + expire: 3600 + expire_at: 1647234000 + expire_on_resolve: false + reason: Planned site maintenance + subscription: entity:sensu-site +{{< /code >}} + +{{< code json >}} +{ + "type": "Silenced", + "api_version": "core/v2", + "metadata": { + "name": "entity:sensu-site:check-http" + }, + "spec": { + "begin": 1647230400, + "check": "check-http", + "creator": "admin", + "expire": 3600, + "expire_at": 1647234000, + "expire_on_resolve": false, + "reason": "Planned site maintenance", + "subscription": "entity:sensu-site" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## What's next + +When your silence goes into effect at the designated `begin` time, you will still see events for `check-http` on the `sensu-site` entity in the Sensu web UI. +This is because **silences do not stop events from being produced — they stop events from being handled**. + +If you followed this guide to create the `check-http` check on the `sensu-site` entity, you might have noticed that the check does not include a [pipeline][14]. +To observe the silenced entry's effect, add a pipeline to the `check-http` check definition (or recreate the [silenced entry][15] with your own entity and a check that includes a pipeline). +The pipeline must include a workflow with the built-in [`not_silenced`][13] event filter and a handler. + +{{% notice warning %}} +**WARNING**: By default, silenced events will be handled unless the pipeline workflow includes the built-in [`not_silenced`](../../observe-filter/filters/#built-in-filter-not_silenced) event filter to discard silenced events. +{{% /notice %}} + +Follow one of these guides to add a pipeline to your check: + +- [Send email alerts with a pipeline][17] +- [Send PagerDuty alerts with Sensu][18] +- [Send Slack alerts with a pipeline][19] + +Read the [silencing reference][7] for in-depth documentation about silenced entries and more examples for other silencing scenarios. + +Learn more about the [sensu/http-checks][12] [dynamic runtime asset][24]. + +The example in this guide uses [RFC 3339 format][25] with space delimiters and numeric zone offset, but sensuctl supports several [time formats][26] for the `begin` flag. + + +[1]: ../handlers/ +[2]: ../silencing/#silencing-examples +[3]: ../silencing/#silence-a-specific-check-on-a-specific-entity +[4]: ../silencing/#silence-all-checks-with-a-specific-subscription +[5]: ../silencing/#silence-a-specific-check-on-entities-with-a-specific-subscription +[6]: ../silencing/#silence-a-specific-check-on-every-entity +[7]: ../silencing/ +[8]: ../../../sensuctl/create-manage-resources/#time-formats +[9]: ../silencing/#silence-all-checks-for-entities-with-a-specific-subscription +[10]: ../../../operations/deploy-sensu/install-sensu/#install-the-sensu-backend +[11]: #create-the-check +[12]: https://bonsai.sensu.io/assets/sensu/http-checks +[13]: ../../observe-filter/filters/#built-in-filter-not_silenced +[14]: ../pipelines/ +[15]: #create-the-silenced-entry +[16]: ../send-data-sumo-logic/ +[17]: ../send-email-alerts/ +[18]: ../send-pagerduty-alerts/ +[19]: ../send-slack-alerts/ +[20]: https://www.ietf.org/rfc/rfc3339.txt +[21]: ../../../operations/deploy-sensu/install-sensu/#install-sensu-agents +[22]: ../../../operations/deploy-sensu/install-sensu/#install-sensuctl +[23]: ../../../operations/control-access/rbac/#default-users +[24]: ../../../plugins/assets/ +[25]: https://www.ietf.org/rfc/rfc3339.txt +[26]: ../../../sensuctl/create-manage-resources/#time-formats diff --git a/content/sensu-go/6.12/observability-pipeline/observe-process/populate-metrics-influxdb.md b/content/sensu-go/6.12/observability-pipeline/observe-process/populate-metrics-influxdb.md new file mode 100644 index 0000000000..55291cfc92 --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-process/populate-metrics-influxdb.md @@ -0,0 +1,449 @@ +--- +title: "Populate metrics in InfluxDB with handlers" +linkTitle: "Populate Metrics in InfluxDB" +guide_title: "Populate metrics in InfluxDB with handlers" +type: "guide" +description: "Follow this guide to populate Sensu metrics into the time-series database InfluxDB with a handler, an action the Sensu backend executes when an event occurs." +weight: 160 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: observe-process +--- + +{{% notice protip %}} +**PRO TIP**: You can use the InfluxDB Metrics integration in the [Sensu Catalog](../../../catalog/sensu-catalog/) to send Sensu event data to InfluxDB instead of following this guide. +Follow the Catalog prompts to configure the Sensu resources you need and start processing your observability data with a few clicks. +{{% /notice %}} + +A Sensu event handler is an action the Sensu backend executes when a specific [event][1] occurs. +In this guide, you'll use a [handler][9] to populate the time-series database [InfluxDB][2] with Sensu observability event data. + +Metrics can be collected from [check output][10] (in this guide, a check that generates Prometheus metrics) or the [Sensu StatsD Server][3]. + +## Requirements + +To follow this guide, install the Sensu [backend][14], make sure at least one Sensu [agent][21] is running, and configure [sensuctl][22] to connect to the backend as the [`admin` user][23]. + +The example in this guide relies on the `prometheus_metrics` check from [Collect Prometheus metrics with Sensu][25]. +Before you begin, follow the instructions to add the `sensu/sensu-prometheus-collector` dynamic runtime asset and the `prometheus_metrics` check. + +## Configure a Sensu entity + +Every Sensu agent has a defined set of subscriptions that determine which checks the agent will execute. +For an agent to execute a specific check, you must specify the same subscription in the agent configuration and the check definition. + +The example in this guide uses the `prometheus_metrics` check from Collect Prometheus metrics with Sensu, which includes the subscription `app_tier`. +Use sensuctl to add an `app_tier` subscription to one of your entities. + +Before you run the following code, replace `` with the name of the entity on your system. + +{{% notice note %}} +**NOTE**: To find your entity name, run `sensuctl entity list`. +The `ID` is the name of your entity. +{{% /notice %}} + +{{< code shell >}} +sensuctl entity update +{{< /code >}} + +- For `Entity Class`, press enter. +- For `Subscriptions`, type `app_tier` and press enter. + +Run this command to confirm both Sensu services are running: + +{{< code shell >}} +systemctl status sensu-backend && systemctl status sensu-agent +{{< /code >}} + +The response should indicate `active (running)` for both the Sensu backend and agent. + +## Register the dynamic runtime asset + +Dynamic runtime assets are shareable, reusable packages that make it easier to deploy Sensu plugins. +This example uses the sensu/sensu-influxdb-handler dynamic runtime asset to power an InfluxDB handler. + +Use `sensuctl asset add` to register the sensu/sensu-influxdb-handler dynamic runtime asset: + +{{< code shell >}} +sensuctl asset add sensu/sensu-influxdb-handler:3.7.0 -r sensu-influxdb-handler +{{< /code >}} + +The response will confirm that the asset was added: + +{{< code text >}} +fetching bonsai asset: sensu/sensu-influxdb-handler:3.7.0 -r sensu-influxdb-handler +added asset: sensu/sensu-influxdb-handler:3.7.0 + +You have successfully added the Sensu asset resource, but the asset will not get downloaded until +it's invoked by another Sensu resource (ex. check). To add this runtime asset to the appropriate +resource, populate the "runtime_assets" field with ["sensu-influxdb-handler"]. +{{< /code >}} + +This example uses the `-r` (rename) flag to specify a shorter name for the dynamic runtime asset: `sensu-influxdb-handler`. + +You can also download the latest dynamic runtime asset definition for your platform from [Bonsai][13] and register the asset with `sensuctl create --file filename.yml` or `sensuctl create --file filename.json`. + +Run `sensuctl asset list` to confirm that the dynamic runtime asset is ready to use. + +{{% notice note %}} +**NOTE**: Sensu does not download and install dynamic runtime asset builds onto the system until they are needed for command execution. +{{% /notice %}} + +## Create the handler + +Now that you have registered the dynamic runtime asset, use sensuctl to create a handler called `influxdb-handler` that pipes observation data (events) to InfluxDB with the sensu/sensu-influxdb-handler dynamic runtime asset. +Edit the command below to replace the placeholders for database name, address, username, and password with the information for your own InfluxDB database. + +{{< code shell >}} +sensuctl handler create influxdb-handler \ +--type pipe \ +--command "sensu-influxdb-handler -d sensu" \ +--env-vars "INFLUXDB_ADDR=http://influxdb.default.svc.cluster.local:8086, INFLUXDB_USER=sensu, INFLUXDB_PASS=password" \ +--runtime-assets sensu-influxdb-handler +{{< /code >}} + +You should receive a confirmation message: + +{{< code text >}} +Created +{{< /code >}} + +To review the complete resource definition for the handler resource you just created with sensuctl, run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl handler info influxdb-handler --format yaml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl handler info influxdb-handler --format wrapped-json +{{< /code >}} + +{{< /language-toggle >}} + +The `influxdb-handler` resource definition will be similar to this example: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Handler +api_version: core/v2 +metadata: + name: influxdb-handler +spec: + command: sensu-influxdb-handler -d sensu + env_vars: + - INFLUXDB_ADDR=http://influxdb.default.svc.cluster.local:8086 + - INFLUXDB_USER=sensu + - INFLUXDB_PASS=password + filters: null + handlers: null + runtime_assets: + - sensu-influxdb-handler + secrets: null + timeout: 0 + type: pipe +{{< /code >}} + +{{< code json >}} +{ + "type": "Handler", + "api_version": "core/v2", + "metadata": { + "name": "influxdb-handler" + }, + "spec": { + "command": "sensu-influxdb-handler -d sensu", + "env_vars": [ + "INFLUXDB_ADDR=http://influxdb.default.svc.cluster.local:8086", + "INFLUXDB_USER=sensu", + "INFLUXDB_PASS=password" + ], + "filters": null, + "handlers": null, + "runtime_assets": [ + "sensu-influxdb-handler" + ], + "secrets": null, + "timeout": 0, + "type": "pipe" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Create a pipeline that includes the InfluxDB handler + +With your handler configured, you can add it to a pipeline workflow. +A single pipeline workflow can include one or more filters, one mutator, and one handler. + +In this case, the pipeline includes the built-in has_metrics and not_silenced event filters and the InfluxDB handler you've already configured. +To create the pipeline, run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +cat << EOF | sensuctl create +--- +type: Pipeline +api_version: core/v2 +metadata: + name: metrics_pipeline +spec: + workflows: + - name: influxdb_metrics + filters: + - name: has_metrics + type: EventFilter + api_version: core/v2 + - name: not_silenced + type: EventFilter + api_version: core/v2 + handler: + name: influxdb-handler + type: Handler + api_version: core/v2 +EOF +{{< /code >}} + +{{< code shell "JSON" >}} +cat << EOF | sensuctl create +{ + "type": "Pipeline", + "api_version": "core/v2", + "metadata": { + "name": "metrics_pipeline" + }, + "spec": { + "workflows": [ + { + "name": "influxdb_metrics", + "filters": [ + { + "name": "has_metrics", + "type": "EventFilter", + "api_version": "core/v2" + }, + { + "name": "not_silenced", + "type": "EventFilter", + "api_version": "core/v2" + } + ], + "handler": { + "name": "influxdb-handler", + "type": "Handler", + "api_version": "core/v2" + } + } + ] + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + +Now you can add the `metrics_pipeline` pipeline to a check for check output metric extraction. + +## Add the pipeline to a check + +Add the `metrics_pipeline` pipeline to the `prometheus_metrics` check to use it for check output metric extraction. +The check already uses the `influxdb_line` output metric format, but you will need to add the pipeline to extract the metrics and process them according to the pipeline's workflows. + +To open the check definition in your text editor, run: + +{{< code shell >}} +sensuctl edit check prometheus_metrics +{{< /code >}} + +Make two changes in the `prometheus_metrics` check definition: + +1. Delete the `output_metrics_handlers` attribute and value. + +2. Replace the `pipelines: []` line with the following array to reference your `metrics_pipeline` pipeline: + + {{< language-toggle >}} +{{< code yml >}} +pipelines: +- type: Pipeline + api_version: core/v2 + name: metrics_pipeline +{{< /code >}} +{{< code json >}} +{ + "pipelines": [ + { + "type": "Pipeline", + "api_version": "core/v2", + "name": "metrics_pipeline" + } + ] +} +{{< /code >}} +{{< /language-toggle >}} + +Save the two changes and exit the text editor. +You should receive a confirmation message: + +{{< code text >}} +Updated /api/core/v2/namespaces/default/checks/prometheus_metrics +{{< /code >}} + +To review the updated check resource definition, run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl check info prometheus_metrics --format yaml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl check info prometheus_metrics --format wrapped-json +{{< /code >}} + +{{< /language-toggle >}} + +The updated `prometheus_metrics` check definition will be similar to this example: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: prometheus_metrics +spec: + check_hooks: null + command: sensu-prometheus-collector -prom-url http://localhost:9090 -prom-query up + env_vars: null + handlers: [] + high_flap_threshold: 0 + interval: 10 + low_flap_threshold: 0 + output_metric_format: influxdb_line + output_metric_handlers: null + pipelines: + - api_version: core/v2 + name: metrics_pipeline + type: Pipeline + proxy_entity_name: "" + publish: true + round_robin: false + runtime_assets: + - sensu-prometheus-collector + secrets: null + stdin: false + subdue: null + subscriptions: + - app_tier + timeout: 0 + ttl: 0 +{{< /code >}} + +{{< code json >}} +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "prometheus_metrics" + }, + "spec": { + "check_hooks": null, + "command": "sensu-prometheus-collector -prom-url http://localhost:9090 -prom-query up", + "env_vars": null, + "handlers": [], + "high_flap_threshold": 0, + "interval": 10, + "low_flap_threshold": 0, + "output_metric_format": "influxdb_line", + "output_metric_handlers": null, + "pipelines": [ + { + "api_version": "core/v2", + "name": "metrics_pipeline", + "type": "Pipeline" + } + ], + "proxy_entity_name": "", + "publish": true, + "round_robin": false, + "runtime_assets": [ + "sensu-prometheus-collector" + ], + "secrets": null, + "stdin": false, + "subdue": null, + "subscriptions": [ + "app_tier" + ], + "timeout": 0, + "ttl": 0 + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Assign the InfluxDB handler to the Sensu StatsD listener + +To assign your `influxdb-handler` resource to the Sensu StatsD listener at agent startup and pass all StatsD metrics into InfluxDB: + +{{< code shell >}} +sensu-agent start --statsd-event-handlers influxdb-handler +{{< /code >}} + +## Validate the InfluxDB handler + +It might take a few moments for Sensu to receive metrics after you assign the pipeline to the check or assign the handler to the StatsD server. +After an event is handled, metrics should start populating InfluxDB. +You can verify proper handler behavior with `sensu-backend` logs. +Read [Troubleshoot Sensu][8] for log locations by platform. + +Whenever an event is being handled, a log entry is added with the message `"handler":"influxdb-handler","level":"debug","msg":"sending event to handler"`, followed by a second log entry with the message `"msg":"pipelined executed event pipe +handler","output":"","status":0`. + +## What's next + +Now that you know how to apply an InfluxDB handler to metrics, read [Aggregate metrics with the Sensu StatsD listener][3] to learn more about using Sensu to implement StatsD and take action on observability events. + +Read more about the Sensu features you used in this guide: + +- [Subscriptions][19] +- [Dynamic runtime assets][12] and the [sensu/sensu-influxdb-handler][13] asset +- [Pipelines][16] +- [Built-in event filters][17] +- [sensuctl][18] + +You can share, reuse, and maintain the Sensu resources you created just like you would code: save the resource definitions to a file and start building a [monitoring as code repository][7]. + + +[1]: ../../observe-events/events/ +[2]: https://github.com/influxdata/influxdb +[3]: ../aggregate-metrics-statsd/ +[4]: https://github.com/sensu/sensu-influxdb-handler#installation +[5]: ../../../sensuctl/sensuctl-bonsai/#install-dynamic-runtime-asset-definitions +[7]: ../../../operations/monitoring-as-code/ +[8]: ../../../operations/maintain-sensu/troubleshoot/ +[9]: ../handlers/ +[10]: ../../observe-schedule/prometheus-metrics/ +[11]: https://github.com/sensu/sensu-influxdb-handler/releases +[12]: ../../../plugins/assets/ +[13]: https://bonsai.sensu.io/assets/sensu/sensu-influxdb-handler +[14]: ../../../operations/deploy-sensu/install-sensu/#install-the-sensu-backend +[16]: ../pipelines/ +[17]: ../../observe-filter/filters/#built-in-event-filters +[18]: ../../../sensuctl/ +[19]: ../../observe-schedule/subscriptions/ +[21]: ../../../operations/deploy-sensu/install-sensu/#install-sensu-agents +[22]: ../../../operations/deploy-sensu/install-sensu/#install-sensuctl +[23]: ../../../operations/control-access/rbac/#default-users +[24]: ../../observe-process/send-data-sumo-logic/ +[25]: ../../observe-schedule/prometheus-metrics/#collect-prometheus-metrics-with-sensu diff --git a/content/sensu-go/6.12/observability-pipeline/observe-process/send-data-sumo-logic.md b/content/sensu-go/6.12/observability-pipeline/observe-process/send-data-sumo-logic.md new file mode 100644 index 0000000000..fc38a8449f --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-process/send-data-sumo-logic.md @@ -0,0 +1,608 @@ +--- +title: "Send data to Sumo Logic with Sensu" +linkTitle: "Send Data to Sumo Logic" +guide_title: "Send data to Sumo Logic with Sensu" +type: "guide" +description: "Put Sensu's observability pipeline into action. Follow this guide to configure a handler to send Sensu data to Sumo Logic for long-term log and metrics storage." +weight: 180 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: observe-process +--- + +{{% notice protip %}} +**PRO TIP**: You can use the Sumo Logic Analytics integration in the [Sensu Catalog](../../../catalog/sensu-catalog/) to send Sensu event data to Sumo Logic instead of following this guide. +Follow the Catalog prompts to configure the Sensu resources you need and start processing your observability data with a few clicks. +{{% /notice %}} + +Follow this guide to create a pipeline that sends data from a Sensu check to Sumo Logic for long-term logs and metrics storage. +Sensu [checks][2] are commands the Sensu agent executes that generate observability data in a status or metric [event][16]. +Sensu [pipelines][14] define the event filters and actions the Sensu backend executes on the events. + +## Requirements + +To follow this guide, install the Sensu [backend][21], make sure at least one Sensu [agent][23] is running, and configure [sensuctl][22] to connect to the backend as the [`admin` user][24]. + +The examples in this guide rely on the `check_cpu` check from [Monitor server resources with checks][27]. +Before you begin, follow the instructions to [add the `sensu/check-cpu-usage`][28] dynamic runtime asset and the [`check_cpu`][29] check. + +## Configure a Sensu entity + +Sensu checks have a subscriptions attribute, where you specify strings to indicate which subscribers will execute the checks. +For Sensu to execute a check, at least one entity must include a subscription that matches a subscription in the check definition. +In the example in this guide, the `check_cpu` check includes the `system` subscription, so at least one entity must subscribe to `system` to run the check. + +First, select the entity whose data you want to send to Sumo Logic. +To list all of your entities in the current namespace, run: + +{{< code shell >}} +sensuctl entity list +{{< /code >}} + +The `ID` in the response is the entity name. +Select one of the listed entities. + +Before you run the following sensuctl command, replace `` with the name of your entity. +Then run the command to add the `system` subscription to your entity: + +{{< code shell >}} +sensuctl entity update +{{< /code >}} + +- For `Entity Class`, press enter. +- For `Subscriptions`, type `system` and press enter. + +Finally, confirm that both Sensu services are running: + +{{< code shell >}} +systemctl status sensu-backend && systemctl status sensu-agent +{{< /code >}} + +The response should indicate `active (running)` for both the Sensu backend and agent. + +## Register the dynamic runtime asset + +The sensu/sensu-sumologic-handler dynamic runtime asset includes the scripts your handler will need to send observability data to Sumo Logic. + +To add the sensu/sensu-sumologic-handler asset, run: + +{{< code shell >}} +sensuctl asset add sensu/sensu-sumologic-handler:0.3.0 -r sumologic-handler +{{< /code >}} + +This example uses the `-r` (rename) flag to specify a shorter name for the dynamic runtime asset: `sumologic-handler`. + +The response will indicate that the asset was added: + +{{< code text >}} +fetching bonsai asset: sensu/sensu-sumologic-handler:0.3.0 +added asset: sensu/sensu-sumologic-handler:0.3.0 + +You have successfully added the Sensu asset resource, but the asset will not get downloaded until +it's invoked by another Sensu resource (ex. check). To add this runtime asset to the appropriate +resource, populate the "runtime_assets" field with ["sumologic-handler"]. +{{< /code >}} + +To confirm that the asset was added to your Sensu backend, run: + +{{< code shell >}} +sensuctl asset info sumologic-handler +{{< /code >}} + +The response will list the available builds for the sensu/sensu-sumologic-handler dynamic runtime asset. + +{{% notice note %}} +**NOTE**: Sensu does not download and install dynamic runtime asset builds onto the system until they are needed for command execution. +{{% /notice %}} + +## Set up an HTTP Logs and Metrics Source + +Set up a Sumo Logic HTTP Logs and Metrics Source to collect your Sensu observability data. + +{{% notice note %}} +**NOTE**: If you have an existing Sumo Logic HTTP Logs and Metrics Source, you can send Sensu data there instead of creating a new source if you wish. +Copy the HTTP Source Address URL for your existing source and skip to [Add the Sumo Logic handler](#add-the-sumo-logic-handler). +{{% /notice %}} + +Log in to your Sumo Logic account and follow these instructions: + +1. In the Sumo Logic left-navigation menu, click **Manage Data** and then **Collection** to open the Collection tab. + + {{< figure src="/images/go/sensu_plus/manage_data_collection.png" alt="Open the Collections tab" link="/images/go/sensu_plus/manage_data_collection.png" target="_blank" >}} + +2. At the top-right of the Collection tab, click **Add Collector**. + + {{< figure src="/images/go/sensu_plus/add_collector.png" alt="Add a Sumo Logic collector" link="/images/go/sensu_plus/add_collector.png" target="_blank" >}} + +3. In the Click Selector Type modal window, click **Hosted Collector**. + + {{< figure src="/images/go/sensu_plus/hosted_collector_option.png" alt="Select the hosted collector option" link="/images/go/sensu_plus/hosted_collector_option.png" target="_blank" >}} + +4. In the Add Hosted Collector modal window: + - Type **sensu** in the Name field. + - Click **Save**. + + {{< figure src="/images/go/sensu_plus/add_hosted_collector.png" alt="Name the hosted collector" link="/images/go/sensu_plus/add_hosted_collector.png" target="_blank" >}} + +5. In the Confirm prompt, click **OK**. + + {{< figure src="/images/go/sensu_plus/confirm_prompt.png" alt="Confirm your hosted collector configuration" link="/images/go/sensu_plus/confirm_prompt.png" target="_blank" >}} + +6. Under Cloud APIs, click **HTTP Logs & Metrics**. + + {{< figure src="/images/go/sensu_plus/cloud_apis_http_logs_and_metrics.png" alt="Select the HTTP Logs & Metrics source" link="/images/go/sensu_plus/cloud_apis_http_logs_and_metrics.png" target="_blank" >}} + +7. In the HTTP Logs & Metrics form: + - Type **sensu-http** in the Name field. + - Type **sensu-events** in the Source Category field. + - Click **Save**. + + {{< figure src="/images/go/sensu_plus/http_logs_and_metrics_source.png" alt="Select options for HTTP Logs & Metrics source" link="/images/go/sensu_plus/http_logs_and_metrics_source.png" target="_blank" >}} + +8. In the HTTP Source Address prompt, copy the listed URL and click OK. +You will use this URL in the next step as the `SUMOLOGIC_URL` value for the secret in your Sensu handler definition. + + {{< figure src="/images/go/sensu_plus/http_source_address_url.png" alt="Retrieve the HTTP Source Address URL" link="/images/go/sensu_plus/http_source_address_url.png" target="_blank" >}} + +## Add the Sumo Logic handler + +Now that you've set up a Sumo Logic HTTP Logs and Metrics Source, you can create a handler that uses the sensu/sensu-sumologic-handler dynamic runtime asset to send observability data to Sumo Logic. + +The Sensu Sumo Logic Handler asset requires a `SUMOLOGIC_URL` variable. +The value for the `SUMOLOGIC_URL` variable is the Sumo Logic HTTP Source Address URL, which you retrieved in the last step of setting up an HTTP Logs and Metrics Source. + +{{% notice note %}} +**NOTE**: This example shows how to set your Sumo Logic HTTP Source Address URL as an environment variable and use it as a secret with Sensu's `Env` secrets provider. +{{% /notice %}} + +### Configure the SUMOLOGIC_URL environment variable + +To save your Sumo Logic HTTP Source Address URL as an environment variable: + +1. Create the files from which the `sensu-backend` service will read environment variables. +If you have already created this file on your system, skip to step 2. + + {{< language-toggle >}} + +{{< code shell "Debian family" >}} +sudo touch /etc/default/sensu-backend +{{< /code >}} + +{{< code shell "RHEL family" >}} +sudo touch /etc/sysconfig/sensu-backend +{{< /code >}} + + {{< /language-toggle >}} + +2. In the following code, replace `` with your Sumo Logic HTTP Source Address URL. +Run: + + {{< language-toggle >}} + +{{< code shell "Debian family" >}} +echo 'SUMOLOGIC_URL=' | sudo tee -a /etc/default/sensu-backend +{{< /code >}} + +{{< code shell "RHEL family" >}} +echo 'SUMOLOGIC_URL=' | sudo tee -a /etc/sysconfig/sensu-backend +{{< /code >}} + +{{< /language-toggle >}} + +3. Restart the sensu-backend: + + {{< code shell >}} +sudo systemctl restart sensu-backend +{{< /code >}} + +This configures the `SUMOLOGIC_URL` environment variable to your Sumo Logic HTTP Source Address URL in the context of the sensu-backend process. + +### Create the Env secret + +Create a secret named `sumologic_url` that refers to the environment variable ID `SUMOLOGIC_URL`. +Run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +cat << EOF | sensuctl create +--- +type: Secret +api_version: secrets/v1 +metadata: + name: sumologic_url +spec: + id: SUMOLOGIC_URL + provider: env +EOF +{{< /code >}} + +{{< code shell "JSON" >}} +cat << EOF | sensuctl create +{ + "type": "Secret", + "api_version": "secrets/v1", + "metadata": { + "name": "sumologic_url" + }, + "spec": { + "id": "SUMOLOGIC_URL", + "provider": "env" + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + +Now you can refer to the `sumologic_url` secret in your handler to securely pass your Sumo Logic HTTP Source Address URL. + +### Create a Sumo Logic handler + +Run the following command to create a handler to send Sensu observability data to your Sumo Logic HTTP Logs and Metrics Source: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +cat << EOF | sensuctl create +--- +type: Handler +api_version: core/v2 +metadata: + name: sumologic +spec: + command: >- + sensu-sumologic-handler --send-log --send-metrics + --source-host "{{ .Entity.Name }}" + --source-name "{{ .Check.Name }}" + type: pipe + runtime_assets: + - sumologic-handler + secrets: + - name: SUMOLOGIC_URL + secret: sumologic_url +EOF +{{< /code >}} + +{{< code shell "JSON" >}} +cat << EOF | sensuctl create +{ + "type": "Handler", + "api_version": "core/v2", + "metadata": { + "name": "sumologic" + }, + "spec": { + "command": "sensu-sumologic-handler --send-log --send-metrics --source-host \"{{ .Entity.Name }}\" --source-name \"{{ .Check.Name }}\"", + "type": "pipe", + "runtime_assets": [ + "sumologic-handler" + ], + "secrets": [ + { + "name": "SUMOLOGIC_URL", + "secret": "sumologic_url" + } + ] + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + +Make sure that your handler was added by retrieving the complete handler definition in YAML or JSON format: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl handler info sumologic --format yaml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl handler info sumologic --format wrapped-json +{{< /code >}} + +{{< /language-toggle >}} + +The response will list the complete handler resource definition: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Handler +api_version: core/v2 +metadata: + name: sumologic +spec: + command: sensu-sumologic-handler --send-log --send-metrics --source-host "{{ .Entity.Name }}" --source-name "{{ .Check.Name }}" + env_vars: null + filters: null + handlers: null + runtime_assets: + - sumologic-handler + secrets: + - name: SUMOLOGIC_URL + secret: sumologic_url + timeout: 0 + type: pipe +{{< /code >}} + +{{< code json >}} +{ + "type": "Handler", + "api_version": "core/v2", + "metadata": { + "name": "sumologic" + }, + "spec": { + "command": "sensu-sumologic-handler --send-log --send-metrics --source-host \"{{ .Entity.Name }}\" --source-name \"{{ .Check.Name }}\"", + "env_vars": null, + "filters": null, + "handlers": null, + "runtime_assets": [ + "sumologic-handler" + ], + "secrets": [ + { + "name": "SUMOLOGIC_URL", + "secret": "sumologic_url" + } + ], + "timeout": 0, + "type": "pipe" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Create a pipeline with the Sumo Logic handler + +With your Sumo Logic handler configured, you can add it to a [pipeline][14] workflow. +A single pipeline workflow can include one or more event filters, one mutator, and one handler. + +To send data for all events (as opposed to only incidents), create a pipeline that includes only the Sumo Logic handler you've already configured and the built-in [not_silenced event filter][20] — no mutators. +To add the pipeline, run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +cat << EOF | sensuctl create +--- +type: Pipeline +api_version: core/v2 +metadata: + name: sensu_to_sumo +spec: + workflows: + - name: logs_to_sumologic + filters: + - name: not_silenced + type: EventFilter + api_version: core/v2 + handler: + name: sumologic + type: Handler + api_version: core/v2 +EOF +{{< /code >}} + +{{< code shell "JSON" >}} +cat << EOF | sensuctl create +{ + "type": "Pipeline", + "api_version": "core/v2", + "metadata": { + "name": "sensu_to_sumo" + }, + "spec": { + "workflows": [ + { + "name": "logs_to_sumologic", + "filters": [ + { + "name": "not_silenced", + "type": "EventFilter", + "api_version": "core/v2" + } + ], + "handler": { + "name": "sumologic", + "type": "Handler", + "api_version": "core/v2" + } + } + ] + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + +## Assign the pipeline to a check + +To use the `sensu_to_sumo` pipeline, list it in a check definition's pipelines array. +This example uses the `check_cpu` check created in Monitor server resources, but you can add the pipeline to any Sensu check you wish. +All the observability events that the check produces will be processed according to the pipeline's workflows. + +Assign your `sensu_to_sumo` pipeline to the `check_cpu` check to start sending Sensu data to Sumo Logic. + +To open the check definition in your text editor, run: + +{{< code shell >}} +sensuctl edit check check_cpu +{{< /code >}} + +Replace the `pipelines: []` line with the following array: + +{{< code yml >}} + pipelines: + - type: Pipeline + api_version: core/v2 + name: sensu_to_sumo +{{< /code >}} + +To confirm that the updated `check_cpu` resource definition includes the pipelines reference, run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl check info check_cpu --format yaml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl check info check_cpu --format wrapped-json +{{< /code >}} + +{{< /language-toggle >}} + +The updated check definition will be similar to this example: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: CheckConfig +api_version: core/v2 +metadata: + created_by: admin + name: check_cpu +spec: + check_hooks: null + command: check-cpu-usage -w 75 -c 90 + env_vars: null + handlers: [] + high_flap_threshold: 0 + interval: 15 + low_flap_threshold: 0 + output_metric_format: prometheus_text + output_metric_handlers: null + pipelines: + - api_version: core/v2 + name: sensu_to_sumo + type: Pipeline + proxy_entity_name: "" + publish: true + round_robin: false + runtime_assets: + - check-cpu-usage + secrets: null + stdin: false + subdue: null + subscriptions: + - system + timeout: 0 + ttl: 0 +{{< /code >}} + +{{< code json >}} +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "check_cpu", + "created_by": "admin" + }, + "spec": { + "check_hooks": null, + "command": "check-cpu-usage -w 75 -c 90", + "env_vars": null, + "handlers": [], + "high_flap_threshold": 0, + "interval": 15, + "low_flap_threshold": 0, + "output_metric_format": "prometheus_text", + "output_metric_handlers": null, + "pipelines": [ + { + "api_version": "core/v2", + "name": "sensu_to_sumo", + "type": "Pipeline" + } + ], + "proxy_entity_name": "", + "publish": true, + "round_robin": false, + "runtime_assets": [ + "check-cpu-usage" + ], + "secrets": null, + "stdin": false, + "subdue": null, + "subscriptions": [ + "system" + ], + "timeout": 0, + "ttl": 0 + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## View your Sensu data in Sumo Logic + +It will take a few moments after you add the pipeline to the check for your Sensu observability data to appear in Sumo Logic. +Use the Live Tail feature to confirm that your data is reaching Sumo Logic. + +1. In Sumo Logic, click the **+ New** button and select **Live Tail** from the drop-down menu. + + {{< figure src="/images/go/send_data_to_sumo_logic/new_button_live_tail.png" alt="Click the + New button and select Live Tail" link="/images/go/send_data_to_sumo_logic/new_button_live_tail.png" target="_blank" >}} + +2. In the Live Tail search field, enter `_collector=sensu` and click **Run**. + + {{< figure src="/images/go/send_data_to_sumo_logic/live_tail_run_button.png" alt="Location of Live Tail Run button" link="/images/go/send_data_to_sumo_logic/live_tail_run_button.png" target="_blank" >}} + +Within a few seconds, the Live Tail page should begin to display your Sensu observability data. + +{{< figure src="/images/go/send_data_to_sumo_logic/live_tail_running.png" alt="Live Tail results for the 'sensu' collector" link="/images/go/send_data_to_sumo_logic/live_tail_running.png" target="_blank" >}} + + +If you see Sensu data on the Live Tail page, well done! +You have a successful workflow that sends Sensu observability data to your Sumo Logic account. + +## What's next + +To share and reuse the check, handler, and pipeline like code, [save them to files][6] and start building a [monitoring as code repository][7]. + +Learn more about the [sensu/sensu-sumologic-handler][8] [dynamic runtime asset][5]. +You can also configure a [Sumo Logic dashboard][10] to search, view, and analyze the Sensu data you're sending to your Sumo Logic [HTTP Logs and Metrics Source][1]. + +In addition to the traditional handler we used in this example, you can use [Sensu Plus][17], our built-in integration, to send metrics to Sumo Logic with a streaming [Sumo Logic metrics handler][18]. + + +[1]: https://help.sumologic.com/03Send-Data/Sources/02Sources-for-Hosted-Collectors/HTTP-Source +[2]: ../../observe-schedule/checks/ +[3]: ../../observe-schedule/monitor-server-resources/ +[4]: ../../../operations/deploy-sensu/install-sensu/ +[5]: ../../../plugins/assets/ +[6]: ../../../operations/monitoring-as-code/#build-as-you-go +[7]: ../../../operations/monitoring-as-code/ +[8]: https://bonsai.sensu.io/assets/sensu/sensu-sumologic-handler +[9]: ../handlers/ +[10]: https://help.sumologic.com/Visualizations-and-Alerts/Dashboards +[11]: ../../observe-schedule/subscriptions/ +[12]: #set-up-an-http-logs-and-metrics-source +[13]: https://help.sumologic.com/05Search/Live-Tail +[14]: ../pipelines/ +[15]: ../../observe-schedule/checks/#pipelines-attribute +[16]: ../../observe-events/ +[17]: ../../../sensu-plus/ +[18]: ../sumo-logic-metrics-handlers/ +[19]: ../../../plugins/featured-integrations/sumologic/ +[20]: ../../observe-filter/filters/#built-in-filter-not_silenced +[21]: ../../../operations/deploy-sensu/install-sensu/#install-the-sensu-backend +[22]: ../../../operations/deploy-sensu/install-sensu/#install-sensuctl +[23]: ../../../operations/deploy-sensu/install-sensu/#install-sensu-agents +[24]: ../../../operations/control-access/rbac/#default-users +[25]: https://bonsai.sensu.io/ +[26]: ../../../plugins/assets/ +[27]: ../../observe-schedule/monitor-server-resources/ +[28]: ../../observe-schedule/monitor-server-resources/#register-the-sensucheck-cpu-usage-asset +[29]: ../../observe-schedule/monitor-server-resources/#create-a-check-to-monitor-a-server diff --git a/content/sensu-go/6.12/observability-pipeline/observe-process/send-email-alerts.md b/content/sensu-go/6.12/observability-pipeline/observe-process/send-email-alerts.md new file mode 100644 index 0000000000..7a455b4c6b --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-process/send-email-alerts.md @@ -0,0 +1,431 @@ +--- +title: "Send email alerts with a pipeline" +linkTitle: "Send Email Alerts" +guide_title: "Send email alerts with a pipeline" +type: "guide" +description: "Send notifications based on Sensu Go observability event data to an email address to alert you of incidents and help you resolve them more quickly." +weight: 200 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: observe-process +--- + +{{% notice protip %}} +**PRO TIP**: You can use the Email Alerts integration in the [Sensu Catalog](../../../catalog/sensu-catalog/) to send email alerts based on Sensu event data instead of following this guide. +Follow the Catalog prompts to configure the Sensu resources you need and start processing your observability data with a few clicks. +{{% /notice %}} + +Pipelines are Sensu resources composed of [observation event][1] processing workflows that include filters, mutators, and handlers. +You can use pipelines to send email alerts, create or resolve incidents (in PagerDuty, for example), or store metrics in a time-series database like InfluxDB. + +When you are using Sensu in production, events will come from a check or metric you configure. +For this guide, you will create an ad hoc event that you can trigger manually to test your email handler. + +Your backend will execute a pipeline with a handler that sends notifications to the email address you specify. +The pipeline will also include an [event filter][5] to make sure you only receive a notification when your event represents a status change. + +## Requirements + +To follow this guide, install the Sensu [backend][12], make sure at least one Sensu [agent][13] is running, and configure [sensuctl][4] to connect to the backend as the [`admin` user][19]. + +## Add the email handler dynamic runtime asset + +Dynamic runtime assets are shareable, reusable packages that help you deploy Sensu plugins. +In this guide, you'll use the sensu/sensu-email-handler dynamic runtime asset to power an `email` handler. + +Use the following sensuctl example to register the sensu/sensu-email-handler dynamic runtime asset: + +{{< code shell >}} +sensuctl asset add sensu/sensu-email-handler:1.2.2 -r email-handler +{{< /code >}} + +The response will confirm that the asset was added: + +{{< code text >}} +fetching bonsai asset: sensu/sensu-email-handler:1.2.2 +added asset: sensu/sensu-email-handler:1.2.2 + +You have successfully added the Sensu asset resource, but the asset will not get downloaded until +it's invoked by another Sensu resource (ex. check). To add this runtime asset to the appropriate +resource, populate the "runtime_assets" field with ["email-handler"]. +{{< /code >}} + +The -r (rename) flag allows you to specify a shorter name for the dynamic runtime asset (in this case, `email-handler`). + +To confirm that the handler dynamic runtime asset was added correctly, run: + +{{< code shell >}} +sensuctl asset list +{{< /code >}} + +The list should include the `email-handler` dynamic runtime asset. +For a detailed list of everything related to the asset that Sensu added automatically, run: + +{{< code shell >}} +sensuctl asset info email-handler +{{< /code >}} + +The sensu/sensu-email-handler dynamic runtime asset includes the `sensu-email-handler` command, which you will use when you create the email handler definition later in this guide. + +{{% notice note %}} +**NOTE**: Sensu does not download and install dynamic runtime asset builds onto the system until they are needed for command execution. +{{% /notice %}} + +## Add an event filter + +Event filters allow you to fine-tune how your events are handled and reduce alert fatigue. +In this guide, your event filter will send notifications only when your event's state changes (for example, for any change between `0` OK, `1` warning, and `2` critical). + +Here's an overview of how the `state_change_only` filter will work: + +- If your event status changes from `0` to `1`, you will receive **one** email notification for the change to warning status. +- If your event status stays at `1` for the next hour, you **will not** receive repeated email notifications during that hour. +- If your event status changes to `2` after 1 hour at `1`, you will receive **one** email notification for the change from warning to critical status. +- If your event status fluctuates between `0`, `1`, and `2` for the next hour, you will receive **one** email notification **each time** the status changes. + +To create the event filter, run: + +{{< language-toggle >}} + +{{< code text "YML" >}} +cat << EOF | sensuctl create +--- +type: EventFilter +api_version: core/v2 +metadata: + annotations: null + labels: null + name: state_change_only +spec: + action: allow + expressions: + - event.check.occurrences == 1 + runtime_assets: [] +EOF +{{< /code >}} + +{{< code text "JSON" >}} +cat << EOF | sensuctl create +{ + "type": "EventFilter", + "api_version": "core/v2", + "metadata": { + "annotations": null, + "labels": null, + "name": "state_change_only" + }, + "spec": { + "action": "allow", + "expressions": [ + "event.check.occurrences == 1" + ], + "runtime_assets": [ + + ] + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + +## Create the email handler definition + +After you add an event filter, create the email handler definition to specify the email address where the handler will send notifications. +In the handler definition's `command` value, you'll need to change a few things: + +- ``: Replace with the email address you want to use to send email alerts. +- ``: Replace with the email address you want to receive email alerts. +- ``: Replace with the hostname of your SMTP server. +- ``: Replace with your SMTP username, typically your email address. +- ``: Replace with your SMTP password, typically the same as your email password. + +{{% notice note %}} +**NOTE**: To use Gmail or G Suite as your SMTP server, follow Google's instructions to [send email via SMTP](https://support.google.com/a/answer/176600?hl=en). +If you have enabled 2-step verification on your Google account, use an [app password](https://support.google.com/accounts/answer/185833?hl=en) instead of your login password. +If you have not enabled 2-step verification, you may need to adjust your [app access settings](https://support.google.com/accounts/answer/6010255) to follow the example in this guide. +{{% /notice %}} + +After you update the command with your email, server, username, and password values in the example below, run the updated code to create the email handler definition: + +{{< language-toggle >}} + +{{< code text "YML" >}} +cat << EOF | sensuctl create +--- +api_version: core/v2 +type: Handler +metadata: + name: email +spec: + type: pipe + command: sensu-email-handler -f -t -s -u username -p password + timeout: 10 + runtime_assets: + - email-handler +EOF +{{< /code >}} + +{{< code text "JSON" >}} +cat << EOF | sensuctl create +{ + "api_version": "core/v2", + "type": "Handler", + "metadata": { + "name": "email" + }, + "spec": { + "type": "pipe", + "command": "sensu-email-handler -f -t -s -u username -p password", + "timeout": 10, + "runtime_assets": [ + "email-handler" + ] + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + +## Create a pipeline + +With your event filter and handler configured, you can build a pipeline workflow. +A single pipeline workflow can include one or more filters, one mutator, and one handler. + +In this case, the pipeline includes your `state_change_only` event filter and `email` handler, as well as two built-in event filters, is_incident and not_silenced. +These two built-in filters are included in every Sensu backend installation, so you don't have to create them. +The is_incident and not_silenced event filters ensure that you receive alerts for unsilenced events with *only* warning (`1`) or critical (`2`) status: + +To create the pipeline, run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +cat << EOF | sensuctl create +--- +type: Pipeline +api_version: core/v2 +metadata: + name: alerts_pipeline +spec: + workflows: + - name: email_alerts + filters: + - name: state_change_only + type: EventFilter + api_version: core/v2 + - name: is_incident + type: EventFilter + api_version: core/v2 + - name: not_silenced + type: EventFilter + api_version: core/v2 + handler: + name: email + type: Handler + api_version: core/v2 +EOF +{{< /code >}} + +{{< code shell "JSON" >}} +cat << EOF | sensuctl create +{ + "type": "Pipeline", + "api_version": "core/v2", + "metadata": { + "name": "alerts_pipeline" + }, + "spec": { + "workflows": [ + { + "name": "email_alerts", + "filters": [ + { + "name": "state_change_only", + "type": "EventFilter", + "api_version": "core/v2" + }, + { + "name": "is_incident", + "type": "EventFilter", + "api_version": "core/v2" + }, + { + "name": "not_silenced", + "type": "EventFilter", + "api_version": "core/v2" + } + ], + "handler": { + "name": "email", + "type": "Handler", + "api_version": "core/v2" + } + } + ] + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + +Before your pipeline can send alerts to your email, you need an event that generates the alerts. +In the final step, you will create an ad hoc event that you can trigger manually. + +## Create and trigger an ad hoc event + +To create an ad hoc event, first use `sensuctl env` to set up environment variables. +The environment variables will provide the required Sensu API access token credential for the Sensu API: + +{{< code shell >}} +eval $(sensuctl env) +{{< /code >}} + +Verify that the `SENSU_ACCESS_TOKEN` environment variable is set by echoing its value: + +{{< code shell >}} +echo $SENSU_ACCESS_TOKEN +{{< /code >}} + +The response will list the `SENSU_ACCESS_TOKEN` value. + +With the environment variables set, you can use the Sensu API to create your ad hoc observability event. + +{{% notice note %}} +**NOTE**: The example events use the default namespace. +If you are using a different namespace, replace `default` in the event definitions and the API URLs with the name of the desired namespace. +{{% /notice %}} + +This event outputs the message "Everything is OK.” when it occurs: + +{{< code shell >}} +curl -sS -H 'Content-Type: application/json' \ +-H "Authorization: Bearer $SENSU_ACCESS_TOKEN" \ +-d '{ + "entity": { + "entity_class": "proxy", + "metadata": { + "name": "server01", + "namespace": "default" + } + }, + "check": { + "metadata": { + "name": "server-health" + }, + "output": "Everything is OK.", + "status": 0 + } +}' \ +http://localhost:8080/api/core/v2/namespaces/default/events +{{< /code >}} + +As configured, the event status is `0` (OK). +Now it's time to trigger an event and view the results! + +To generate a status change event, use the update event endpoint to create a `1` (warning) event. +Run: + +{{< code shell >}} +curl -sS -X PUT \ +-H "Authorization: Bearer $SENSU_ACCESS_TOKEN" \ +-H 'Content-Type: application/json' \ +-d '{ + "entity": { + "entity_class": "proxy", + "metadata": { + "name": "server01", + "namespace": "default" + } + }, + "check": { + "metadata": { + "name": "server-health" + }, + "output": "This is a warning.", + "status": 1 + }, + "pipelines": [ + { + "type": "Pipeline", + "api_version": "core/v2", + "name": "alerts_pipeline" + } + ] +}' \ +http://localhost:8080/api/core/v2/namespaces/default/events/server01/server-health +{{< /code >}} + +{{% notice note %}} +**NOTE**: If you receive an `invalid credentials` error, refresh your token. +Run `eval $(sensuctl env)`. +{{% /notice %}} + +Check your email — you should receive a message from Sensu! + +Create another event with status set to `0`. Run: + +{{< code shell >}} +curl -sS -X PUT \ +-H "Authorization: Bearer $SENSU_ACCESS_TOKEN" \ +-H 'Content-Type: application/json' \ +-d '{ + "entity": { + "entity_class": "proxy", + "metadata": { + "name": "server01", + "namespace": "default" + } + }, + "check": { + "metadata": { + "name": "server-health" + }, + "output": "Everything is OK.", + "status": 0 + }, + "pipelines": [ + { + "type": "Pipeline", + "api_version": "core/v2", + "name": "alerts_pipeline" + } + ] +}' \ +http://localhost:8080/api/core/v2/namespaces/default/events/server01/server-health +{{< /code >}} + +You should receive another email because the event status changed to `0` (OK). + +## Next steps + +Now that you know how to apply a pipeline to a check and take action on events, reuse this email pipeline with the `check_cpu` check from our [Monitor server resources][2] guide. +Check out [Route alerts with event filters][7] for a complex pipeline example that includes several workflows with different event filters and handlers. + +The [sensu/sensu-email-handler][3] dynamic runtime asset makes it possible to [add a template][14] that provides context for your email notifications. +The email template functionality uses tokens to populate the values provided by the event, and you can use HTML to format the email. + + +[1]: ../../observe-events/events/ +[2]: ../../observe-schedule/monitor-server-resources/ +[3]: https://bonsai.sensu.io/assets/sensu/sensu-email-handler +[4]: ../../../operations/deploy-sensu/install-sensu/#install-sensuctl +[5]: ../../observe-filter/filters/ +[6]: ../pipelines/ +[7]: ../../observe-filter/route-alerts/ +[8]: ../../../plugins/assets/ +[10]: ../../observe-filter/filters/#built-in-filter-is_incident +[11]: ../../observe-filter/filters/#built-in-filter-not_silenced +[12]: ../../../operations/deploy-sensu/install-sensu/#install-the-sensu-backend +[13]: ../../../operations/deploy-sensu/install-sensu/#install-sensu-agents +[14]: https://bonsai.sensu.io/assets/sensu/sensu-email-handler#templates +[15]: ../../../operations/monitoring-as-code/ +[16]: ../../observe-filter/filters/ +[17]: #create-an-ad-hoc-event +[18]: #create-the-email-handler-definition +[19]: ../../../operations/control-access/rbac/#default-users diff --git a/content/sensu-go/6.12/observability-pipeline/observe-process/send-pagerduty-alerts.md b/content/sensu-go/6.12/observability-pipeline/observe-process/send-pagerduty-alerts.md new file mode 100644 index 0000000000..ccb2a394f3 --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-process/send-pagerduty-alerts.md @@ -0,0 +1,470 @@ +--- +title: "Send PagerDuty alerts with Sensu" +linkTitle: "Send PagerDuty Alerts" +guide_title: "Send PagerDuty alerts with Sensu" +type: "guide" +description: "Follow this guide to configure a check that generates status events and a handler that sends Sensu alerts to PagerDuty for non-OK events." +weight: 220 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: observe-process +--- + +{{% notice protip %}} +**PRO TIP**: You can use the PagerDuty integration in the [Sensu Catalog](../../../catalog/sensu-catalog/) to send alerts based on Sensu event data instead of following this guide. +Follow the Catalog prompts to configure the Sensu resources you need and start processing your observability data with a few clicks. +{{% /notice %}} + +Follow this guide to create a pipeline that sends incident alerts to PagerDuty and add the pipeline to a check named `check_cpu`. +Sensu [checks][2] are commands the Sensu agent executes that generate observability data in a status or metric [event][19]. +Sensu [pipelines][20] define the event filters and actions the Sensu backend executes on the events. + +## Requirements + +To follow this guide, install the Sensu [backend][4], make sure at least one Sensu [agent][23] is running, and configure [sensuctl][24] to connect to the backend as the [`admin` user][25]. + +You'll also need your [PagerDuty API integration key][1] to set up the handler in this guide. + +The example in this guide relies on the `check_cpu` check from [Monitor server resources with checks][3]. +Before you begin, follow the instructions to [add the `sensu/check-cpu-usage`][28] dynamic runtime asset and the [`check_cpu`][29] check. + +## Configure a Sensu entity + +Every Sensu agent has a defined set of subscriptions that determine which checks the agent will execute. +For an agent to execute a specific check, you must specify the same subscription in the agent configuration and the check definition. +To run the `check_cpu` check, you'll need a Sensu entity with the subscription `system`. + +First, find your entity name: + +{{< code shell >}} +sensuctl entity list +{{< /code >}} + +The `ID` in the response is the name of your entity. + +Replace `` with the name of your entity in the sensuctl command below. +Then run the command to add the `system` subscription to your entity: + +{{< code shell >}} +sensuctl entity update +{{< /code >}} + +- For `Entity Class`, press enter. +- For `Subscriptions`, type `system` and press enter. + +Confirm both Sensu services are running: + +{{< code shell >}} +systemctl status sensu-backend && systemctl status sensu-agent +{{< /code >}} + +The response should indicate `active (running)` for both the Sensu backend and agent. + +## Register the dynamic runtime asset + +The sensu/sensu-pagerduty-handler dynamic runtime asset includes the scripts you will need to send events to PagerDuty. + +To add the sensu/sensu-pagerduty-handler asset, run: + +{{< code shell >}} +sensuctl asset add sensu/sensu-pagerduty-handler:2.2.0 -r pagerduty-handler +{{< /code >}} + +This example uses the `-r` (rename) flag to specify a shorter name for the dynamic runtime asset: `pagerduty-handler`. + +The response will indicate that the asset was added: + +{{< code text >}} +fetching bonsai asset: sensu/sensu-pagerduty-handler:2.2.0 +added asset: sensu/sensu-pagerduty-handler:2.2.0 + +You have successfully added the Sensu asset resource, but the asset will not get downloaded until +it's invoked by another Sensu resource (ex. check). To add this runtime asset to the appropriate +resource, populate the "runtime_assets" field with ["pagerduty-handler"]. +{{< /code >}} + +To confirm that the asset was added to your Sensu backend, run: + +{{< code shell >}} +sensuctl asset info pagerduty-handler +{{< /code >}} + +The response will list the available builds for the Sensu PagerDuty Handler dynamic runtime asset. + +{{% notice note %}} +**NOTE**: Sensu does not download and install dynamic runtime asset builds onto the system until they are needed for command execution. +{{% /notice %}} + +## Add the PagerDuty handler + +Now that you've added the dynamic runtime asset, you can create a handler that uses the asset to send non-OK events to PagerDuty. + +In the following command, replace `` with your [PagerDuty API integration key][1]. +Then run the updated command: + +{{< code shell >}} +sensuctl handler create pagerduty \ +--type pipe \ +--runtime-assets pagerduty-handler \ +--command "sensu-pagerduty-handler -t " +{{< /code >}} + +Make sure that your handler was added by retrieving the complete handler definition in YAML or JSON format: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl handler info pagerduty --format yaml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl handler info pagerduty --format wrapped-json +{{< /code >}} + +{{< /language-toggle >}} + +The response will list the complete handler resource definition: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Handler +api_version: core/v2 +metadata: + name: pagerduty +spec: + command: sensu-pagerduty-handler -t + env_vars: null + handlers: null + runtime_assets: + - pagerduty-handler + secrets: null + timeout: 0 + type: pipe +{{< /code >}} + +{{< code json >}} +{ + "type": "Handler", + "api_version": "core/v2", + "metadata": { + "name": "pagerduty" + }, + "spec": { + "command": "sensu-pagerduty-handler -t ", + "env_vars": null, + "handlers": null, + "runtime_assets": [ + "pagerduty-handler" + ], + "secrets": null, + "timeout": 0, + "type": "pipe" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Create a pipeline with event filters and a handler + +With your handler configured, you can add it to a pipeline workflow. +A single pipeline workflow can include one or more filters, one mutator, and one handler. + +In this case, the pipeline includes the built-in is_incident and not_silenced event filters, as well as the `pagerduty` handler you've already configured. +To create the pipeline, run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +cat << EOF | sensuctl create +--- +type: Pipeline +api_version: core/v2 +metadata: + name: cpu_check_alerts +spec: + workflows: + - name: pagerduty_alerts + filters: + - name: is_incident + type: EventFilter + api_version: core/v2 + - name: not_silenced + type: EventFilter + api_version: core/v2 + handler: + name: pagerduty + type: Handler + api_version: core/v2 +EOF +{{< /code >}} + +{{< code shell "JSON" >}} +cat << EOF | sensuctl create +{ + "type": "Pipeline", + "api_version": "core/v2", + "metadata": { + "name": "cpu_check_alerts" + }, + "spec": { + "workflows": [ + { + "name": "pagerduty_alerts", + "filters": [ + { + "name": "is_incident", + "type": "EventFilter", + "api_version": "core/v2" + }, + { + "name": "not_silenced", + "type": "EventFilter", + "api_version": "core/v2" + } + ], + "handler": { + "name": "pagerduty", + "type": "Handler", + "api_version": "core/v2" + } + } + ] + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + +## Assign the pipeline to a check + +To use the `cpu_check_alerts` pipeline, list it in a check definition's pipelines array (in this case, the `check_cpu` check created in Monitor server resources. +All the observability events that the check produces will be processed according to the pipeline's workflows. + +Assign your `cpu_check_alerts` pipeline to the `check_cpu` check to receive Slack alerts when the CPU usage of your system reaches the specific thresholds set in the check command. + +To open the check definition in your text editor, run: + +{{< code shell >}} +sensuctl edit check check_cpu +{{< /code >}} + +Replace the `pipelines: []` line with the following array: + +{{< code yml >}} + pipelines: + - type: Pipeline + api_version: core/v2 + name: cpu_check_alerts +{{< /code >}} + +To view the updated `check_cpu` resource definition, run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl check info check_cpu --format yaml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl check info check_cpu --format wrapped-json +{{< /code >}} + +{{< /language-toggle >}} + +The updated check definition will be similar to this example: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: check_cpu +spec: + check_hooks: null + command: check-cpu-usage -w 75 -c 90 + env_vars: null + handlers: [] + high_flap_threshold: 0 + interval: 10 + low_flap_threshold: 0 + output_metric_format: "" + output_metric_handlers: null + pipelines: + - api_version: core/v2 + name: cpu_check_alerts + type: Pipeline + proxy_entity_name: "" + publish: true + round_robin: false + runtime_assets: + - check-cpu-usage + secrets: null + stdin: false + subdue: null + subscriptions: + - system + timeout: 0 + ttl: 0 +{{< /code >}} + +{{< code json >}} +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "check_cpu" + }, + "spec": { + "check_hooks": null, + "command": "check-cpu-usage -w 75 -c 90", + "env_vars": null, + "handlers": [], + "high_flap_threshold": 0, + "interval": 10, + "low_flap_threshold": 0, + "output_metric_format": "", + "output_metric_handlers": null, + "pipelines": [ + { + "api_version": "core/v2", + "name": "cpu_check_alerts", + "type": "Pipeline" + } + ], + "proxy_entity_name": "", + "publish": true, + "round_robin": false, + "runtime_assets": [ + "check-cpu-usage" + ], + "secrets": null, + "stdin": false, + "subdue": null, + "subscriptions": [ + "system" + ], + "timeout": 0, + "ttl": 0 + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Observe an alert in PagerDuty + +It might take a few moments after you add the pipeline to the check for the check to be scheduled on entities with the `system` subscription and the result sent back to Sensu backend. + +As configured, the `cpu_check` command requires CPU usage to reach 75% capacity to send a non-OK event. +To trigger an alert and confirm that the check and pipeline are working properly, adjust the check command to reduce the usage percentage required for a non-OK event. + +To open the check definition in your text editor, run: + +{{< code shell >}} +sensuctl edit check check_cpu +{{< /code >}} + +Replace the `-w` value in the `command` line with `1` and save the updated check definition: + +{{< code yml >}} + command: check-cpu-usage -w 1 -c 90 +{{< /code >}} + +You should see a response to confirm the update: + +{{< code text >}} +Updated /api/core/v2/namespaces/default/checks/check_cpu +{{< /code >}} + +After Sensu detects a non-OK event, the handler in your pipeline will send the alert to your PagerDuty account, where you should see an event similar to this one: + +{{< figure src="/images/go/send_pagerduty_alerts/pipeline_pagerduty_alert_example.png" alt="Example alert in PagerDuty for failing Sensu check" link="/images/go/send_pagerduty_alerts/pipeline_pagerduty_alert_example.png" target="_blank" >}} + +## Resolve the alert in PagerDuty + +To complete your workflow, restore the CPU usage command to 75% so Sensu sends a resolution to PagerDuty. +Open the check definition in your text editor: + +{{< code shell >}} +sensuctl edit check check_cpu +{{< /code >}} + +Replace the `-w` value in the `command` line with `75` and save the updated check definition: + +{{< code yml >}} + command: check-cpu-usage -w 75 -c 90 +{{< /code >}} + +In your PagerDuty account, the alert should now be listed under the "Resolved" tab. + +To view the resolved event with sensuctl, run: + +{{< code shell >}} +sensuctl event list +{{< /code >}} + +The response should show that `cpu_check` has an OK (0) status: + +{{< code text >}} + Entity Check Output Status Silenced Timestamp UUID +─────────────── ─────────── ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── ──────── ────────── ─────────────────────────────── ─────────────────────────────────────── + sensu-centos check_cpu check-cpu-usage OK: 4.17% CPU usage | cpu_idle=95.83, cpu_system=1.04, cpu_user=3.13, cpu_nice=0.00, cpu_iowait=0.00, cpu_irq=0.00, cpu_softirq=0.00, cpu_steal=0.00, cpu_guest=0.00, cpu_guestnice=0.00 0 false 2021-11-17 21:09:07 +0000 UTC xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx +{{< /code >}} + +The web UI Events page will also show that the `cpu_check` check is passing. + +## What's next + +You now have a working set-up with a check and a pipeline that sends alerts to your PagerDuty account. +To share and reuse the check, handler, and pipeline like code, [save them to files][6] and start building a [monitoring as code repository][7]. + +For handlers that use the Sensu PagerDuty Handler dynamic runtime asset (like the one you created in this guide), you can use an alternative method for [authenticating and routing alerts based on PagerDuty teams][17]. +To use this option, list the teams' PagerDuty API integration keys in the handler definition as environment variables or secrets or in the `/etc/default/sensu-backend` configuration file as environment variables. +Then, add check or agent annotations to specify which PagerDuty teams should receive alerts based on check events. +Sensu will look up the key in the handler definition or backend configuration file that corresponds to the team name in the check annotation to authenticate and send alerts. +You can also customize your PagerDuty handler with configuration options like [severity mapping][16] and [event-based templating][18]. + +Learn more about the Sensu resources you used in this guide: + +- [Subscriptions][13] +- [Handlers][9] +- [Pipelines][20] +- Built-in [is_incident][21] and [not_silenced][22] event filters + + +[1]: https://support.pagerduty.com/docs/generating-api-keys#section-events-api-keys +[2]: ../../observe-schedule/checks/ +[3]: ../../observe-schedule/monitor-server-resources/ +[4]: ../../../operations/deploy-sensu/install-sensu/#install-the-sensu-backend +[5]: ../../../plugins/assets/ +[6]: ../../../operations/monitoring-as-code/#build-as-you-go +[7]: ../../../operations/monitoring-as-code/ +[8]: https://bonsai.sensu.io/assets/sensu/sensu-pagerduty-handler +[9]: ../handlers/ +[10]: ../../../operations/deploy-sensu/install-sensu/#3-initialize +[11]: ../../../web-ui/ +[12]: ../../../sensuctl/ +[13]: ../../observe-schedule/subscriptions/ +[14]: ../../../plugins/featured-integrations/pagerduty/ +[15]: ../../../plugins/featured-integrations/pagerduty/#get-the-plugin +[16]: https://bonsai.sensu.io/assets/sensu/sensu-pagerduty-handler#pagerduty-severity-mapping +[17]: https://bonsai.sensu.io/assets/sensu/sensu-pagerduty-handler#pager-teams +[18]: ../handler-templates/ +[19]: ../../observe-events/ +[20]: ../pipelines/ +[21]: ../../observe-filter/filters/#built-in-filter-is_incident +[22]: ../../observe-filter/filters/#built-in-filter-not_silenced +[23]: ../../../operations/deploy-sensu/install-sensu/#install-sensu-agents +[24]: ../../../operations/deploy-sensu/install-sensu/#install-sensuctl +[25]: ../../../operations/control-access/rbac/#default-users +[28]: ../../observe-schedule/monitor-server-resources/#register-the-sensucheck-cpu-usage-asset +[29]: ../../observe-schedule/monitor-server-resources/#create-a-check-to-monitor-a-server diff --git a/content/sensu-go/6.12/observability-pipeline/observe-process/send-slack-alerts.md b/content/sensu-go/6.12/observability-pipeline/observe-process/send-slack-alerts.md new file mode 100644 index 0000000000..cff9d13974 --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-process/send-slack-alerts.md @@ -0,0 +1,507 @@ +--- +title: "Send Slack alerts with a pipeline" +linkTitle: "Send Slack Alerts" +guide_title: "Send Slack alerts with a pipeline" +type: "guide" +description: "Send alerts to Slack with Sensu pipelines, which allow you to send events to alert you of incidents and help you resolve them more quickly." +weight: 240 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: observe-process +--- + +{{% notice protip %}} +**PRO TIP**: You can use the Slack Alerts integration in the [Sensu Catalog](../../../catalog/sensu-catalog/) to send Slack alerts based on Sensu event data instead of following this guide. +Follow the Catalog prompts to configure the Sensu resources you need and start processing your observability data with a few clicks. +{{% /notice %}} + +Pipelines are Sensu resources composed of [observation event][1] processing workflows that include filters, mutators, and handlers. +You can use pipelines to send email alerts, create or resolve incidents (in PagerDuty, for example), or store metrics in a time-series database like InfluxDB. + +This guide will help you send alerts to Slack in the channel `monitoring` by configuring a pipeline and adding it to a check named `check_cpu`. + +## Requirements + +To follow this guide, install the Sensu [backend][17], make sure at least one Sensu [agent][23] is running, and configure [sensuctl][24] to connect to the backend as the [`admin` user][25]. + +The example in this guide relies on the `check_cpu` check from [Monitor server resources with checks][26]. +Before you begin, follow the instructions to [add the `sensu/check-cpu-usage`][27] dynamic runtime asset and the [`check_cpu`][28] check. + +You will also need a [Slack webhook][6] to complete this guide. +If you're already the admin of a Slack, visit `https://YOUR_WORKSPACE_NAME_HERE.slack.com/services/new/incoming-webhook` and follow the steps to add the Incoming WebHooks integration, choose a channel, and save the settings. +If you're not yet a Slack admin, [create a new workspace][12] and then create and save your webhook. +After you save your webhook, you can find the webhook URL under **Integration Settings**. + +## Configure a Sensu entity + +Every Sensu agent has a defined set of subscriptions that determine which checks the agent will execute. +For an agent to execute a specific check, you must specify the same subscription in the agent configuration and the check definition. +To run the `check_cpu` check, you'll need a Sensu entity with the subscription `system`. + +First, find your entity name: + +{{< code shell >}} +sensuctl entity list +{{< /code >}} + +The `ID` in the response is the name of your entity. + +Replace `` with the name of your entity in the sensuctl command below. +Then run the command to add the `system` subscription to your entity: + +{{< code shell >}} +sensuctl entity update +{{< /code >}} + +- For `Entity Class`, press enter. +- For `Subscriptions`, type `system` and press enter. + +Confirm both Sensu services are running: + +{{< code shell >}} +systemctl status sensu-backend && systemctl status sensu-agent +{{< /code >}} + +The response should indicate `active (running)` for both the Sensu backend and agent. + +## Register the dynamic runtime asset + +Dynamic runtime assets are shareable, reusable packages that help you deploy Sensu plugins. +In this guide, you'll use the sensu/sensu-slack-handler dynamic runtime asset to power a `slack` handler. + +Use `sensuctl asset add` to register the sensu/sensu-slack-handler dynamic runtime asset: + +{{< code shell >}} +sensuctl asset add sensu/sensu-slack-handler:1.5.0 -r sensu-slack-handler +{{< /code >}} + +This example uses the `-r` (rename) flag to specify a shorter name for the dynamic runtime asset: `sensu-slack-handler`. + +The response will indicate that the asset was added: + +{{< code text >}} +fetching bonsai asset: sensu/sensu-slack-handler:1.5.0 +added asset: sensu/sensu-slack-handler:1.5.0 + +You have successfully added the Sensu asset resource, but the asset will not get downloaded until +it's invoked by another Sensu resource (ex. check). To add this runtime asset to the appropriate +resource, populate the "runtime_assets" field with ["sensu-slack-handler"]. +{{< /code >}} + +{{% notice note %}} +**NOTE**: Sensu does not download and install dynamic runtime asset builds onto the system until they are needed for command execution. +{{% /notice %}} + +## Create a handler + +Use sensuctl to create a handler called `slack` that pipes observation data (events) to Slack using the sensu/sensu-slack-handler dynamic runtime asset. +Before you run the sensuctl command below, edit it to include your Slack webhook URL and the channel where you want to receive events: + +{{< code shell >}} +sensuctl handler create slack \ +--type pipe \ +--env-vars "SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T0000/B000/XXXXXXXX" \ +--command "sensu-slack-handler --channel '#monitoring'" \ +--runtime-assets sensu-slack-handler +{{< /code >}} + +You should receive a confirmation message: + +{{< code text >}} +Created +{{< /code >}} + +The `sensuctl handler create slack` command creates a handler resource. +To view the `slack` handler definition, run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl handler info slack --format yaml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl handler info slack --format wrapped-json +{{< /code >}} + +{{< /language-toggle >}} + +The `slack` handler resource definition will be similar to this example: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Handler +api_version: core/v2 +metadata: + name: slack +spec: + command: sensu-slack-handler --channel '#monitoring' + env_vars: + - SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T0000/B000/XXXXXXXX + filters: null + handlers: null + runtime_assets: + - sensu-slack-handler + secrets: null + timeout: 0 + type: pipe +{{< /code >}} + +{{< code json >}} +{ + "type": "Handler", + "api_version": "core/v2", + "metadata": { + "name": "slack" + }, + "spec": { + "command": "sensu-slack-handler --channel '#monitoring'", + "env_vars": [ + "SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T0000/B000/XXXXXXXX" + ], + "filters": null, + "handlers": null, + "runtime_assets": [ + "sensu-slack-handler" + ], + "secrets": null, + "timeout": 0, + "type": "pipe" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Create a pipeline that includes the handler + +With your handler configured, you can add it to a pipeline workflow. +A single pipeline workflow can include one or more filters, one mutator, and one handler. + +For now, the pipeline includes only the `slack` handler and the built-in not_silenced event filter so that you receive an alert for every event the check generates (including events with OK status). +To create the pipeline, run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +cat << EOF | sensuctl create +--- +type: Pipeline +api_version: core/v2 +metadata: + name: cpu_check_alerts +spec: + workflows: + - name: slack_alerts + filters: + - name: not_silenced + type: EventFilter + api_version: core/v2 + handler: + name: slack + type: Handler + api_version: core/v2 +EOF +{{< /code >}} + +{{< code shell "JSON" >}} +cat << EOF | sensuctl create +{ + "type": "Pipeline", + "api_version": "core/v2", + "metadata": { + "name": "cpu_check_alerts" + }, + "spec": { + "workflows": [ + { + "name": "slack_alerts", + "filters": [ + { + "name": "not_silenced", + "type": "EventFilter", + "api_version": "core/v2" + } + ], + "handler": { + "name": "slack", + "type": "Handler", + "api_version": "core/v2" + } + } + ] + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + +## Assign the pipeline to a check + +To use the `cpu_check_alerts` pipeline, list it in a check definition's pipelines array. +All the observability events that the check produces will be processed according to the pipeline's workflows. + +Assign your `cpu_check_alerts` pipeline to the `check_cpu` check to receive Slack alerts when the CPU usage of your system reaches the specific thresholds set in the check command. + +To open the check definition in your text editor, run: + +{{< code shell >}} +sensuctl edit check check_cpu +{{< /code >}} + +Replace the `pipelines: []` line with the following array and save the updated check definition: + +{{< language-toggle >}} + +{{< code shell "YML" >}} + pipelines: + - type: Pipeline + api_version: core/v2 + name: cpu_check_alerts +{{< /code >}} + +{{< code shell "JSON" >}} + "pipelines": [ + { + "type": "Pipeline", + "api_version": "core/v2", + "name": "cpu_check_alerts" + } + ] +{{< /code >}} + +{{< /language-toggle >}} + +You should see a response to confirm the update: + +{{< code text >}} +Updated /api/core/v2/namespaces/default/checks/check_cpu +{{< /code >}} + +To view the updated `check_cpu` resource definition, run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl check info check_cpu --format yaml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl check info check_cpu --format wrapped-json +{{< /code >}} + +{{< /language-toggle >}} + +The updated check definition will be similar to this example: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: check_cpu +spec: + check_hooks: null + command: check-cpu-usage -w 75 -c 90 + env_vars: null + handlers: [] + high_flap_threshold: 0 + interval: 10 + low_flap_threshold: 0 + output_metric_format: "" + output_metric_handlers: null + pipelines: + - api_version: core/v2 + name: cpu_check_alerts + type: Pipeline + proxy_entity_name: "" + publish: true + round_robin: false + runtime_assets: + - check-cpu-usage + secrets: null + stdin: false + subdue: null + subscriptions: + - system + timeout: 0 + ttl: 0 +{{< /code >}} + +{{< code json >}} +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "check_cpu" + }, + "spec": { + "check_hooks": null, + "command": "check-cpu-usage -w 75 -c 90", + "env_vars": null, + "handlers": [], + "high_flap_threshold": 0, + "interval": 10, + "low_flap_threshold": 0, + "output_metric_format": "", + "output_metric_handlers": null, + "pipelines": [ + { + "api_version": "core/v2", + "name": "cpu_check_alerts", + "type": "Pipeline" + } + ], + "proxy_entity_name": "", + "publish": true, + "round_robin": false, + "runtime_assets": [ + "check-cpu-usage" + ], + "secrets": null, + "stdin": false, + "subdue": null, + "subscriptions": [ + "system" + ], + "timeout": 0, + "ttl": 0 + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Validate the pipeline + +It might take a few moments after you add the pipeline to the check for the check to be scheduled on entities with the `system` subscription and the result sent back to Sensu backend. +After an event is handled, you should receive a message like this in Slack: + +{{< figure src="/images/go/send_slack_alerts/check_cpu_usage_example_alert.png" alt="Example Slack message" link="/images/go/send_slack_alerts/check_cpu_usage_example_alert.png" target="_blank" >}} + +Verify proper handler behavior with `sensu-backend` logs. + +Whenever an event is being handled, a log entry is added with the message `"handler":"slack","level":"debug","msg":"sending event to handler"`, followed by a second log entry with the message `"msg":"event pipe handler executed","output":"","status":0`. + +{{% notice note %}} +**NOTE**: Read [Troubleshoot Sensu](../../../operations/maintain-sensu/troubleshoot/#log-file-locations) for Sensu log locations by platform. +{{% /notice %}} + +## Add another event filter to the pipeline + +At this point, the `cpu_check_alerts` pipeline has probably sent quite a few Slack messages for events with OK (`0`) status. +To receive alerts for events with *only* warning (`1`) or critical (`2`) status, add the built-in is_incident event filter to the pipeline: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +cat << EOF | sensuctl create +--- +type: Pipeline +api_version: core/v2 +metadata: + name: cpu_check_alerts +spec: + workflows: + - name: slack_alerts + filters: + - name: not_silenced + type: EventFilter + api_version: core/v2 + - name: is_incident + type: EventFilter + api_version: core/v2 + handler: + name: slack + type: Handler + api_version: core/v2 +EOF +{{< /code >}} + +{{< code shell "JSON" >}} +cat << EOF | sensuctl create +{ + "type": "Pipeline", + "api_version": "core/v2", + "metadata": { + "name": "cpu_check_alerts" + }, + "spec": { + "workflows": [ + { + "name": "slack_alerts", + "filters": [ + { + "name": "not_silenced", + "type": "EventFilter", + "api_version": "core/v2" + }, + { + "name": "is_incident", + "type": "EventFilter", + "api_version": "core/v2" + } + ], + "handler": { + "name": "slack", + "type": "Handler", + "api_version": "core/v2" + } + } + ] + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + +Adding the is_incident filter to your pipeline should quickly reduce the number of alerts you receive in Slack. + +## What's next + +Now that you know how to apply a pipeline to a check and take action on events, read the [pipelines reference][8] for in-depth documentation. +Read [Route alerts with event filters][9] for a more complex example with multiple filters and handlers organized into several pipeline workflows. + +For more information about customizing your Slack alerts, read the [sensu/sensu-slack-handler page in Bonsai][14]. + +Follow [Send PagerDuty alerts with Sensu][11] to configure a check that generates status events and a handler that sends Sensu alerts to PagerDuty for non-OK events. + +You can share and reuse Sensu resources like code, including the handler and pipeline you created in this guide — [save the resource definition to a file][15] and start building a [monitoring as code repository][16]. + + +[1]: ../../observe-events/events/ +[2]: ../../observe-schedule/monitor-server-resources/ +[3]: https://github.com/sensu/slack-handler +[4]: https://golang.org/doc/install +[6]: https://api.slack.com/incoming-webhooks +[7]: ../../../operations/maintain-sensu/troubleshoot/#log-file-locations +[8]: ../pipelines/ +[9]: ../../observe-filter/route-alerts/ +[10]: ../../../sensuctl/sensuctl-bonsai/#install-dynamic-runtime-asset-definitions +[11]: ../../../observability-pipeline/observe-process/send-pagerduty-alerts/ +[12]: https://slack.com/get-started#/create +[13]: ../../../plugins/assets/ +[14]: https://bonsai.sensu.io/assets/sensu/sensu-slack-handler +[15]: ../../../operations/monitoring-as-code/#build-as-you-go +[16]: ../../../operations/monitoring-as-code/ +[17]: ../../../operations/deploy-sensu/install-sensu/#install-the-sensu-backend +[18]: ../../observe-schedule/checks/#pipelines-attribute +[19]: ../../observe-filter/filters/#built-in-filter-is_incident +[20]: ../../../sensuctl/ +[21]: ../../observe-schedule/subscriptions/ +[22]: ../../observe-filter/filters/#built-in-filter-not_silenced +[23]: ../../../operations/deploy-sensu/install-sensu/#install-sensu-agents +[24]: ../../../operations/deploy-sensu/install-sensu/#install-sensuctl +[25]: ../../../operations/control-access/rbac/#default-users +[26]: ../../observe-schedule/monitor-server-resources/ +[27]: ../../observe-schedule/monitor-server-resources/#register-the-sensucheck-cpu-usage-asset +[28]: ../../observe-schedule/monitor-server-resources/#create-a-check-to-monitor-a-server diff --git a/content/sensu-go/6.12/observability-pipeline/observe-process/silencing.md b/content/sensu-go/6.12/observability-pipeline/observe-process/silencing.md new file mode 100644 index 0000000000..1bfc390ac0 --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-process/silencing.md @@ -0,0 +1,637 @@ +--- +title: "Silencing reference" +linkTitle: "Silencing Reference" +reference_title: "Silencing" +type: "reference" +description: "Use Sensu’s built-in silencing capability to suppress event handler execution on an ad hoc basis to plan maintenance and reduce alert fatigue." +weight: 60 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: observe-process +--- + +Sensu's silencing capability allows you to suppress event handler execution on an ad hoc basis so you can plan maintenance and reduce alert fatigue. +Silences are created on an ad hoc basis using [sensuctl][17], the [web UI][18], and the [core/v2/silenced][19] API endpoints. + +Successfully created silencing entries are assigned a `name` in the format `$SUBSCRIPTION:$CHECK`, where `$SUBSCRIPTION` is the name of a Sensu entity subscription and `$CHECK` is the name of a Sensu check. +You can use silences to silence checks on specific entities by taking advantage of per-entity subscriptions (for example, `entity:$ENTITY_NAME`). + +When creating a silencing entry, you can specify a combination of checks and subscriptions, but only one or the other is strictly required. +For example, if you create a silencing entry [specifying only a check][12], its name will contain an asterisk (or wildcard) in the `$SUBSCRIPTION` position. +This indicates that any event with a matching check name will be marked as silenced, regardless of the originating entities’ subscriptions. + +Conversely, a silencing entry that [specifies only a subscription][11] will have a name with an asterisk in the `$CHECK` position. +This indicates that any event where the originating entities’ subscriptions match the subscription specified in the entry will be marked as silenced, regardless of the check name. + +These silences are persisted in the Sensu datastore. +When the Sensu server processes subsequent check results, it retrieves matching silences from the store. +If there are one or more matching entries, the event is updated with a list of silenced entry names. +When the check name or subscription described in a silencing entry matches an event, the event will include the [`silenced` attribute][13], which lists the silencing entries that match the event. + +Silenced checks still create events, and events from silenced checks are still passed to handlers. +To prevent handler execution for events from silenced checks, make sure the handler definition includes the [built-in `not_silenced` event filter][14]. +The `not_silenced` event filter prevents handlers from processing events that include the `silenced` attribute. + +## Silencing examples + +This example shows a silencing resource definition that uses a per-entity subscription to silence any alerts on a single Sensu entity, `i-424242`: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Silenced +api_version: core/v2 +metadata: + name: entity:i-424242:* +spec: + begin: 1542671205 + check: null + creator: admin + expire: -1 + expire_at: 0 + expire_on_resolve: false + reason: null + subscription: entity:i-424242 +{{< /code >}} + +{{< code json >}} +{ + "type": "Silenced", + "api_version": "core/v2", + "metadata": { + "name": "entity:i-424242:*" + }, + "spec": { + "expire": -1, + "expire_at": 0, + "expire_on_resolve": false, + "creator": "admin", + "reason": null, + "check": null, + "subscription": "entity:i-424242", + "begin": 1542671205 + } +} +{{< /code >}} + +{{< /language-toggle >}} + +### Silence a specific check on a specific entity + +The following example shows how to silence a check named `check_ntp` on entity `i-424242`, ensuring the silencing entry is deleted after the underlying issue is resolved: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Silenced +api_version: core/v2 +metadata: + name: entity:i-424242:check_ntp +spec: + subscription: entity:i-424242 + check: check_ntp + expire_on_resolve: true +{{< /code >}} + +{{< code json >}} +{ + "type": "Silenced", + "api_version": "core/v2", + "metadata": { + "name": "entity:i-424242:check_ntp" + }, + "spec": { + "subscription": "entity:i-424242", + "check": "check_ntp", + "expire_on_resolve": true + } +} +{{< /code >}} + +{{< /language-toggle >}} + +The optional `expire_on_resolve` attribute used in this example indicates that when the server processes a matching check from the specified entity with status OK, the silencing entry will be removed automatically. + +When used in combination with other attributes (like `creator` and `reason`), this gives Sensu operators a way to acknowledge that they received an alert, suppress additional notifications, and automatically clear the silencing entry when the check status returns to normal. + +## Silencing specification + +### Silenced entry names + +Silences must contain either a subscription or check name and are identified by the combination of `$SUBSCRIPTION:$CHECK`. +If a check or subscription is not provided, it will be substituted with a wildcard (asterisk): `$SUBSCRIPTION:*` or `*:$CHECK`. + +### Top-level attributes + +type | +-------------|------ +description | Top-level attribute that specifies the [`sensuctl create`][4] resource type. Silences should always be type `Silenced`. +required | Required for silencing entry definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][4]. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +type: Silenced +{{< /code >}} +{{< code json >}} +{ + "type": "Silenced" +} +{{< /code >}} +{{< /language-toggle >}} + +api_version | +-------------|------ +description | Top-level attribute that specifies the Sensu API group and version. For silences in this version of Sensu, the `api_version` should always be `core/v2`. +required | Required for silencing entry definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][4]. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +api_version: core/v2 +{{< /code >}} +{{< code json >}} +{ + "api_version": "core/v2" +} +{{< /code >}} +{{< /language-toggle >}} + +metadata | +-------------|------ +description | Top-level collection of metadata about the silencing entry that includes `name`, `namespace`, and `created_by` as well as custom `labels` and `annotations`. The `metadata` map is always at the top level of the silencing entry definition. This means that in `wrapped-json` and `yaml` formats, the `metadata` scope occurs outside the `spec` scope. Read [metadata attributes][3] for details. +required | Required for silencing entry definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][4]. +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +metadata: + name: appserver:mysql_status + namespace: default + created_by: admin + labels: + region: us-west-1 +{{< /code >}} +{{< code json >}} +{ + "metadata": { + "name": "appserver:mysql_status", + "namespace": "default", + "created_by": "admin", + "labels": { + "region": "us-west-1" + } + } +} +{{< /code >}} +{{< /language-toggle >}} + +spec | +-------------|------ +description | Top-level map that includes the silencing entry [spec attributes][5]. +required | Required for silences in `wrapped-json` or `yaml` format for use with [`sensuctl create`][4]. +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +spec: + expire: -1 + expire_at: 0 + expire_on_resolve: false + creator: admin + reason: + check: + subscription: entity:i-424242 + begin: 1542671205 +{{< /code >}} +{{< code json >}} +{ + "spec": { + "expire": -1, + "expire_at": 0, + "expire_on_resolve": false, + "creator": "admin", + "reason": null, + "check": null, + "subscription": "entity:i-424242", + "begin": 1542671205 + } +} +{{< /code >}} +{{< /language-toggle >}} + +### Metadata attributes + +| name | | +-------------|------ +description | Silencing identifier generated from the combination of a subscription name and check name. +required | false - This value cannot be modified. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +name: appserver:mysql_status +{{< /code >}} +{{< code json >}} +{ + "name": "appserver:mysql_status" +} +{{< /code >}} +{{< /language-toggle >}} + +| namespace | | +-------------|------ +description | Sensu [RBAC namespace][2] that the silencing entry belongs to. +required | false +type | String +default | `default` +example | {{< language-toggle >}} +{{< code yml >}} +namespace: production +{{< /code >}} +{{< code json >}} +{ + "namespace": "production" +} +{{< /code >}} +{{< /language-toggle >}} + +| created_by | | +-------------|------ +description | Username of the Sensu user who created the silence or last updated the silence. Sensu automatically populates the `created_by` field when the silence is created or updated. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +created_by: admin +{{< /code >}} +{{< code json >}} +{ + "created_by": "admin" +} +{{< /code >}} +{{< /language-toggle >}} + +| labels | | +-------------|------ +description | Custom attributes to include with observation event data that you can use for response and web UI view filtering.

    If you include labels in your event data, you can filter [API responses][6], [sensuctl responses][7], and [web UI views][9] based on them. In other words, labels allow you to create meaningful groupings for your data.

    Limit labels to metadata you need to use for response filtering. For complex, non-identifying metadata that you will *not* need to use in response filtering, use annotations rather than labels. +required | false +type | Map of key-value pairs. Keys can contain only letters, numbers, and underscores and must start with a letter. Values can be any valid UTF-8 string. +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +labels: + environment: development + region: us-west-2 +{{< /code >}} +{{< code json >}} +{ + "labels": { + "environment": "development", + "region": "us-west-2" + } +} +{{< /code >}} +{{< /language-toggle >}} + +| annotations | | +-------------|------ +description | Non-identifying metadata to include with observation event data that you can access with [event filters][8]. You can use annotations to add data that's meaningful to people or external tools that interact with Sensu.

    In contrast to labels, you cannot use annotations in [API response filtering][6], [sensuctl response filtering][7], or [web UI views][10]. +required | false +type | Map of key-value pairs. Keys and values can be any valid UTF-8 string. +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +annotations: + managed-by: ops + playbook: www.example.url +{{< /code >}} +{{< code json >}} +{ + "annotations": { + "managed-by": "ops", + "playbook": "www.example.url" + } +} +{{< /code >}} +{{< /language-toggle >}} + +### Spec attributes + + + +check | +-------------|------ +description | Name of the check the entry should match. +required | true, unless `subscription` is provided +type | String +example | {{< language-toggle >}} +{{< code yml >}} +check: haproxy_status +{{< /code >}} +{{< code json >}} +{ + "check": "haproxy_status" +} +{{< /code >}} +{{< /language-toggle >}} + +subscription | +-------------|------ +description | Name of the subscription the entry should match. +required | true, unless `check` is provided +type | String +example | {{< language-toggle >}} +{{< code yml >}} +subscription: entity:i-424242 +{{< /code >}} +{{< code json >}} +{ + "subscription": "entity:i-424242" +} +{{< /code >}} +{{< /language-toggle >}} + +begin | +-------------|------ +description | Time at which silence entry goes into effect. In epoch. +required | false +type | Integer +example | {{< language-toggle >}} +{{< code yml >}} +begin: 1512512023 +{{< /code >}} +{{< code json >}} +{ + "begin": 1512512023 +} +{{< /code >}} +{{< /language-toggle >}} + + + +expire | +-------------|------ +description | Number of seconds until the entry should be deleted.

    If the silence is set to expire when a [check resolves][22], the `expire` value will be `-1`.

    If the silence is set to [expire at a specific time][21], the `expire` value will be `0`. +required | false +type | Integer +default | -1 +example | {{< language-toggle >}} +{{< code yml >}} +expire: 3600 +{{< /code >}} +{{< code json >}} +{ + "expire": 3600 +} +{{< /code >}} +{{< /language-toggle >}} + + + +expire_at | +-------------|------ +description | Time at which the entry should be deleted. In seconds since the Unix epoch.

    Use `expire_at` in conjunction with [`expire_on_resolve`][22] to create silences that expire either when a check resolves or at a specific time, whichever comes first. +required | false +type | Integer +default | 0 +example | {{< language-toggle >}} +{{< code yml >}} +expire_at: 1664550303 +{{< /code >}} +{{< code json >}} +{ + "expire_at": 1664550303 +} +{{< /code >}} +{{< /language-toggle >}} + + + +expire_on_resolve | +-------------|------ +description | `true` if the entry should be deleted when the specified [check][20] begins to return OK status (resolves). Otherwise, `false`.

    Use `expire_on_resolve` in conjunction with [`expire_at`][21] to create silences that expire either when a check resolves or at a specific time, whichever comes first. +required | false +type | Boolean +default | false +example | {{< language-toggle >}} +{{< code yml >}} +expire_on_resolve: true +{{< /code >}} +{{< code json >}} +{ + "expire_on_resolve": true +} +{{< /code >}} +{{< /language-toggle >}} + +creator | +-------------|------ +description | Person, application, or entity responsible for creating the entry. +required | false +type | String +default | null +example | {{< language-toggle >}} +{{< code yml >}} +creator: Application Deploy Tool 5.0 +{{< /code >}} +{{< code json >}} +{ + "creator": "Application Deploy Tool 5.0" +} +{{< /code >}} +{{< /language-toggle >}} + +reason | +-------------|------ +description | Explanation of the reason for creating the entry. +required | false +type | String +default | null +example | {{< language-toggle >}} +{{< code yml >}} +reason: rebooting the world +{{< /code >}} +{{< code json >}} +{ + "reason": "rebooting the world" +} +{{< /code >}} +{{< /language-toggle >}} + +## Silence all checks with a specific subscription + +Use this example to create a silencing entry for all checks with the `appserver` subscription: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Silenced +api_version: core/v2 +metadata: + name: appserver +spec: + subscription: appserver +{{< /code >}} + +{{< code json >}} +{ + "type": "Silenced", + "api_version": "core/v2", + "metadata": { + "name": "appserver" + }, + "spec": { + "subscription": "appserver" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +{{% notice note %}} +**NOTE**: This example will not silence entities with the `appserver` subscription. +Checks that do not include the `appserver` subscription will still run on entities that include the `appserver` subscription.

    +To silence all checks for entities with a particular subscription, [use the Sensu web UI](#silence-all-checks-for-entities-with-a-specific-subscription). +{{% /notice %}} + +## Silence all checks for entities with a specific subscription + +To silence all checks for entities with a particular subscription: + +1. Open the [Entities page][16] in the Sensu web UI. +2. Use the search field to search the entities by subscription. +For example, to search for entities with the `system` subscription, enter `"system" in entity.subscriptions`. +3. Click the box to select all. +4. Click **SILENCE**. +5. In the New Silencing Entry dialog window, add any desired silence configuration options. +6. Click **CREATE**. + +The silencing entries will be listed on the [Silences page][18] in the Sensu web UI. + +{{< figure src="/images/go/silencing_reference/silence_entities_by_subscription_660.gif" alt="Silence entities by subscription in the Sensu web UI" link="/images/go/silencing_reference/silence_entities_by_subscription_660.gif" target="_blank" >}} + +## Silence a specific check on entities with a specific subscription + +To silence a check `mysql_status` that is running on Sensu entities with the subscription `appserver`: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Silenced +api_version: core/v2 +metadata: + name: appserver:mysql_status +spec: + subscription: appserver + check: mysql_status +{{< /code >}} + +{{< code json >}} +{ + "type": "Silenced", + "api_version": "core/v2", + "metadata": { + "name": "appserver:mysql_status" + }, + "spec": { + "subscription": "appserver", + "check": "mysql_status" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Silence a specific check on every entity + +To silence the check `mysql_status` on every entity in your infrastructure, regardless of subscriptions, you only need to provide the check name: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Silenced +api_version: core/v2 +metadata: + name: mysql_status +spec: + check: mysql_status +{{< /code >}} + +{{< code json >}} +{ + "type": "Silenced", + "api_version": "core/v2", + "metadata": { + "name": "mysql_status" + }, + "spec": { + "check": "mysql_status" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Delete a silence + +To delete a silencing entry, you must provide its name. + +Subscription-only silencing entry names will contain an asterisk (or wildcard) in the `$SUBSCRIPTION` position, similar to this example: + +{{< language-toggle >}} + +{{< code yml >}} +name: appserver:* +{{< /code >}} + +{{< code json >}} +{ + "name": "appserver:*" +} +{{< /code >}} + +{{< /language-toggle >}} + +Check-only silencing entry names will contain an asterisk (or wildcard) in the `$CHECK` position, similar to this example: + +{{< language-toggle >}} + +{{< code yml >}} +name: '*:mysql_status' +{{< /code >}} + +{{< code json >}} +{ + "name": "*:mysql_status" +} +{{< /code >}} + +{{< /language-toggle >}} + + +[1]: ../../observe-events/events/#attributes +[2]: ../../../operations/control-access/namespaces/ +[3]: #metadata-attributes +[4]: ../../../sensuctl/create-manage-resources/#create-resources +[5]: #spec-attributes +[6]: ../../../api/#response-filtering +[7]: ../../../sensuctl/filter-responses/ +[8]: ../../observe-filter/filters/ +[9]: ../../../web-ui/search#search-for-labels +[10]: ../../../web-ui/search/ +[11]: #silence-all-checks-for-entities-with-a-specific-subscription +[12]: #silence-a-specific-check-on-every-entity +[13]: ../../observe-events/events/#silenced-attribute +[14]: ../../observe-filter/filters/#built-in-filter-not_silenced +[15]: #silencing-examples +[16]: ../../../web-ui/view-manage-resources/#manage-entities +[17]: ../../../sensuctl/create-manage-resources/ +[18]: ../../../web-ui/view-manage-resources/#manage-silences +[19]: ../../../api/core/silenced/ +[20]: #silence-check +[21]: #silence-expireat +[22]: #silence-expireonresolve diff --git a/content/sensu-go/6.12/observability-pipeline/observe-process/sumo-logic-metrics-handlers.md b/content/sensu-go/6.12/observability-pipeline/observe-process/sumo-logic-metrics-handlers.md new file mode 100644 index 0000000000..3028c34bfe --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-process/sumo-logic-metrics-handlers.md @@ -0,0 +1,513 @@ +--- +title: "Sumo Logic metrics handlers reference" +linkTitle: "Sumo Logic Metrics Handlers Reference" +reference_title: "Sumo Logic metrics handlers" +type: "reference" +description: "Read this reference to learn about Sumo Logic metrics handlers, which provide a persistent connection for sending Sensu data to Sumo Logic." +weight: 80 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: observe-process +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access Sumo Logic metrics handlers in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} + +Sensu executes Sumo Logic metrics handlers during the **[process][22]** stage of the [observability pipeline][29]. + +Sumo Logic metrics handlers provide a persistent connection to transmit Sensu observability metrics to a [Sumo Logic HTTP Logs and Metrics Source][3], which helps prevent the data bottlenecks you may experience with traditional [handlers][1]. + +Traditional handlers start a new UNIX process for every Sensu event they receive and require a new connection to send every event. +As you scale up and process more events per second, the rate at which the handler can transmit observability event data decreases. + +Sumo Logic metrics handlers allow you to configure a connection pool with a maximum number of connections for the handler to use and a time limit for request completion. +For example, if 1000 events are queued for transmission, as each connection finishes transmitting an event, it becomes available again and returns to the pool so the handler can use it to send the next event in the queue. + +Sumo Logic metrics handlers will reuse the available connections as long as they can rather than requiring a new connection for every event, which increases event throughput. + +{{% notice note %}} +**NOTE**: Sumo Logic metrics handlers only accept metrics events. +To send status events, use the [Sensu Sumo Logic Handler integration](../../../plugins/featured-integrations/sumologic/) instead. +{{% /notice %}} + +## Sumo Logic metrics handler examples + +This example shows a Sumo Logic metrics handler resource definition configured to send Sensu observability data to a Sumo Logic HTTP Logs and Metrics Source via the `url` attribute: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: SumoLogicMetricsHandler +api_version: pipeline/v1 +metadata: + name: sumologic_http_log_metrics +spec: + url: "https://endpoint5.collection.us2.sumologic.com/receiver/v1/http/xxxxxxxx" + max_connections: 10 + timeout: 30s +{{< /code >}} + +{{< code json >}} +{ + "type": "SumoLogicMetricsHandler", + "api_version": "pipeline/v1", + "metadata": { + "name": "sumologic_http_log_metrics" + }, + "spec": { + "url": "https://endpoint5.collection.us2.sumologic.com/receiver/v1/http/xxxxxxxx", + "max_connections": 10, + "timeout": "30s" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +You can also use [secrets management][14] to avoid exposing the URL in your Sumo Logic metrics handler configuration: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: SumoLogicMetricsHandler +api_version: pipeline/v1 +metadata: + name: sumologic_http_log_metrics +spec: + url: $SUMO_LOGIC_SOURCE_URL + secrets: + - name: SUMO_LOGIC_SOURCE_URL + secret: sumologic_metrics_us2 + max_connections: 10 + timeout: 30s +{{< /code >}} + +{{< code json >}} +{ + "type": "SumoLogicMetricsHandler", + "api_version": "pipeline/v1", + "metadata": { + "name": "sumologic_http_log_metrics" + }, + "spec": { + "url": "$SUMO_LOGIC_SOURCE_URL", + "secrets": [ + { + "name": "SUMO_LOGIC_SOURCE_URL", + "secret": "sumologic_metrics_us2" + } + ], + "max_connections": 10, + "timeout": "30s" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Use Sumo Logic metrics handlers + +Sumo Logic metrics handlers are commercial resources and are available for use **only** in [pipelines][2]. + +{{% notice note %}} +**NOTE**: Sumo Logic metrics handlers **are not** used by listing the handler name in the check [handlers attribute](../../observe-schedule/checks/#handlers-array). +{{% /notice %}} + +To use a Sumo Logic metrics handler, list it as the [handler][11] in a [pipeline][2] definition. +For example, this pipeline definition uses the [sumologic_http_log_metrics example][12] along with the built-in [has_metrics][13] event filter: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Pipeline +api_version: core/v2 +metadata: + name: metrics_workflows +spec: + workflows: + - name: metrics_to_sumologic + filters: + - name: has_metrics + type: EventFilter + api_version: core/v2 + handler: + name: sumologic_http_log_metrics + type: SumoLogicMetricsHandler + api_version: pipeline/v1 +{{< /code >}} + +{{< code json >}} +{ + "type": "Pipeline", + "api_version": "core/v2", + "metadata": { + "name": "metrics_workflows" + }, + "spec": { + "workflows": [ + { + "name": "metrics_to_sumologic", + "filters": [ + { + "name": "has_metrics", + "type": "EventFilter", + "api_version": "core/v2" + } + ], + "handler": { + "name": "sumologic_http_log_metrics", + "type": "SumoLogicMetricsHandler", + "api_version": "pipeline/v1" + } + } + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Sumo Logic metrics handler specification + +### Top-level attributes + +type | +-------------|------ +description | Top-level attribute that specifies the [`sensuctl create`][4] resource type. Sumo Logic metrics handlers should always be type `SumoLogicMetricsHandler`. +required | Required for Sumo Logic metrics handler definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][4]. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +type: SumoLogicMetricsHandler +{{< /code >}} +{{< code json >}} +{ + "type": "SumoLogicMetricsHandler" +} +{{< /code >}} +{{< /language-toggle >}} + +api_version | +-------------|------ +description | Top-level attribute that specifies the Sensu API group and version. For Sumo Logic metrics handlers in this version of Sensu, the `api_version` should always be `pipeline/v1`. +required | Required for Sumo Logic metrics handler definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][4]. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +api_version: pipeline/v1 +{{< /code >}} +{{< code json >}} +{ + "api_version": "pipeline/v1" +} +{{< /code >}} +{{< /language-toggle >}} + +metadata | +-------------|------ +description | Top-level collection of metadata about the Sumo Logic metrics handler that includes `name`, `namespace`, and `created_by` as well as custom `labels` and `annotations`. The `metadata` map is always at the top level of the handler definition. This means that in `wrapped-json` and `yaml` formats, the `metadata` scope occurs outside the `spec` scope. Read [metadata attributes][8] for details. +required | Required for Sumo Logic metrics handler definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][4]. +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +metadata: + name: sumologic_http_log_metrics + namespace: default + created_by: admin + labels: + environment: development + region: us-west-2 + annotations: + managed-by: ops +{{< /code >}} +{{< code json >}} +{ + "metadata": { + "name": "sumologic_http_log_metrics", + "namespace": "default", + "created_by": "admin", + "labels": { + "environment": "development", + "region": "us-west-2" + }, + "annotations": { + "managed-by": "ops" + } + } +} +{{< /code >}} +{{< /language-toggle >}} + +spec | +-------------|------ +description | Top-level map that includes the Sumo Logic metrics handler [spec attributes][5]. +required | Required for Sumo Logic metrics handler definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][4]. +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +spec: + url: $SUMO_LOGIC_SOURCE_URL + secrets: + - name: SUMO_LOGIC_SOURCE_URL + secret: sumologic_metrics_us2 + max_connections: 10 + timeout: 30s +{{< /code >}} +{{< code json >}} +{ + "spec": { + "url": "$SUMO_LOGIC_SOURCE_URL", + "secrets": [ + { + "name": "SUMO_LOGIC_SOURCE_URL", + "secret": "sumologic_metrics_us2" + } + ], + "max_connections": 10, + "timeout": "30s" + } +} +{{< /code >}} +{{< /language-toggle >}} + +### Metadata attributes + +| name | | +-------------|------ +description | Unique string used to identify the Sumo Logic metrics handler. Sumo Logic metrics handler names cannot contain special characters or spaces (validated with Go regex [`\A[\w\.\-]+\z`][18]). Each Sumo Logic metrics handler must have a unique name within its namespace. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +name: sumologic_http_log_metrics +{{< /code >}} +{{< code json >}} +{ + "name": "sumologic_http_log_metrics" +} +{{< /code >}} +{{< /language-toggle >}} + +| namespace | | +-------------|------ +description | Sensu [RBAC namespace][9] that the Sumo Logic metrics handler belongs to. +required | false +type | String +default | `default` +example | {{< language-toggle >}} +{{< code yml >}} +namespace: default +{{< /code >}} +{{< code json >}} +{ + "namespace": "default" +} +{{< /code >}} +{{< /language-toggle >}} + +| created_by | | +-------------|------ +description | Username of the Sensu user who created the Sumo Logic metrics handler or last updated the Sumo Logic metrics handler. Sensu automatically populates the `created_by` field when the Sumo Logic metrics handler is created or updated. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +created_by: admin +{{< /code >}} +{{< code json >}} +{ + "created_by": "admin" +} +{{< /code >}} +{{< /language-toggle >}} + +| labels | | +-------------|------ +description | Custom attributes to include with observation event data that you can use for response and web UI view filtering.

    If you include labels in your event data, you can filter [API responses][15], [sensuctl responses][16], and [web UI views][25] based on them. In other words, labels allow you to create meaningful groupings for your data.

    Limit labels to metadata you need to use for response filtering. For complex, non-identifying metadata that you will *not* need to use in response filtering, use annotations rather than labels. +required | false +type | Map of key-value pairs. Keys can contain only letters, numbers, and underscores and must start with a letter. Values can be any valid UTF-8 string. +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +labels: + environment: development + region: us-west-2 +{{< /code >}} +{{< code json >}} +{ + "labels": { + "environment": "development", + "region": "us-west-2" + } +} +{{< /code >}} +{{< /language-toggle >}} + +| annotations | | +-------------|------ +description | Non-identifying metadata to include with observation event data that you can access with [event filters][24]. You can use annotations to add data that's meaningful to people or external tools that interact with Sensu.

    In contrast to labels, you cannot use annotations in [API response filtering][15], [sensuctl response filtering][16], or [web UI views][28]. +required | false +type | Map of key-value pairs. Keys and values can be any valid UTF-8 string. +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +annotations: + managed-by: ops +{{< /code >}} +{{< code json >}} +{ + "annotations": { + "managed-by": "ops" + } +} +{{< /code >}} +{{< /language-toggle >}} + +### Spec attributes + +url | +-------------|------ +description | The URL for the Sumo Logic HTTP Logs and Metrics Source where Sensu should transmit the observability metrics. You can also provide the URL as a [secret][6]. +required | true +type | String +example without secrets | {{< language-toggle >}} +{{< code yml >}} +url: https://endpoint5.collection.us2.sumologic.com/receiver/v1/http/xxxxxxxx +{{< /code >}} +{{< code json >}} +{ + "url": "https://endpoint5.collection.us2.sumologic.com/receiver/v1/http/xxxxxxxx" +} +{{< /code >}} +{{< /language-toggle >}} +example with secrets | {{< language-toggle >}} +{{< code yml >}} +url: $SUMO_LOGIC_SOURCE_URL +{{< /code >}} +{{< code json >}} +{ + "url": "$SUMO_LOGIC_SOURCE_URL" +} +{{< /code >}} +{{< /language-toggle >}} + +secrets | +-------------|------ +description | Array of the name/secret pairs to use with command execution. Read [secrets attributes][6] for details. You can also provide the Sumo Logic HTTP Logs and Metrics Source URL directly in the [url attribute][5] instead of configuring a secret. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +secrets: +- name: SUMO_LOGIC_SOURCE_URL + secret: sumologic_metrics_us2 +{{< /code >}} +{{< code json >}} +{ + "secrets": [ + { + "name": "SUMOLOGIC_METRICS_URL", + "secret": "sumologic_metrics_us2" + } + ] +} +{{< /code >}} +{{< /language-toggle >}} + +max_connections | +-------------|------ +description | Maximum number of connections to keep alive in the connection pool. If set to `0`, there is no limit to the number of connections in the pool. +required | false +type | Integer +example | {{< language-toggle >}} +{{< code yml >}} +max_connections: 10 +{{< /code >}} +{{< code json >}} +{ + "max_connections": 10 +} +{{< /code >}} +{{< /language-toggle >}} + +timeout | +-------------|------ +description | Duration to allow for processing a Sumo Logic call. In seconds. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +timeout: 10s +{{< /code >}} +{{< code json >}} +{ + "timeout": "10s" +} +{{< /code >}} +{{< /language-toggle >}} + +### Secrets attributes + +name | +-------------|------ +description | Name of the [secret][10] defined in the handler's URL attribute. Becomes the environment variable presented to the handler. Read [Use secrets management in Sensu][7] for more information. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +name: SUMOLOGIC_METRICS_URL +{{< /code >}} +{{< code json >}} +{ + "name": "SUMOLOGIC_METRICS_URL" +} +{{< /code >}} +{{< /language-toggle >}} + +secret | +-------------|------ +description | Name of the Sensu secret resource that defines how to retrieve the [secret][10]. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +secret: sumologic_metrics_us2 +{{< /code >}} +{{< code json >}} +{ + "secret": "sumologic_metrics_us2" +} +{{< /code >}} +{{< /language-toggle >}} + + +[1]: ../handlers/ +[2]: ../pipelines/ +[3]: https://help.sumologic.com/03Send-Data/Sources/02Sources-for-Hosted-Collectors/HTTP-Source +[4]: ../../../sensuctl/create-manage-resources/#create-resources +[5]: #spec-attributes +[6]: #secrets-attributes +[7]: ../../../operations/manage-secrets/secrets-management/ +[8]: #metadata-attributes +[9]: ../../../operations/control-access/namespaces/ +[10]: ../../../operations/manage-secrets/secrets/ +[11]: ../pipelines/#handlers-pipeline +[12]: #sumo-logic-metrics-handler-example +[13]: ../../observe-filter/filters/#built-in-filter-has_metrics +[14]: ../../../operations/manage-secrets/secrets-management/ +[15]: ../../../api/#response-filtering +[16]: ../../../sensuctl/filter-responses/ +[18]: https://regex101.com/r/zo9mQU/2 +[22]: ../ +[24]: ../../observe-filter/filters/ +[25]: ../../../web-ui/search#search-for-labels +[28]: ../../../web-ui/search/ +[29]: ../../../observability-pipeline/ diff --git a/content/sensu-go/6.12/observability-pipeline/observe-process/tcp-stream-handlers.md b/content/sensu-go/6.12/observability-pipeline/observe-process/tcp-stream-handlers.md new file mode 100644 index 0000000000..2bacdb2b18 --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-process/tcp-stream-handlers.md @@ -0,0 +1,470 @@ +--- +title: "TCP stream handlers reference" +linkTitle: "TCP Stream Handlers Reference" +reference_title: "TCP stream handlers" +type: "reference" +description: "Read this reference to use TCP stream handlers to send observability data to TCP sockets without the data bottlenecks of traditional TCP handlers." +weight: 90 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: observe-process +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access TCP stream handlers in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} + +Sensu executes TCP stream handlers during the **[process][22]** stage of the [observability pipeline][29]. + +Like traditional [TCP handlers][1], TCP stream handlers send observability event data to TCP sockets for external services to consume. +However, TCP stream handlers can help prevent the data bottlenecks you may experience with traditional TCP handlers. + +Traditional TCP handlers start a new UNIX process for every Sensu event they receive and require a new connection to send every event. +As you scale up and process more events per second, the rate at which the TCP handler can transmit observability event data decreases. + +TCP stream handlers allow you to configure a connection pool with a maximum number of connections for the handler to use. +For example, suppose you configure a TCP stream handler with a pool of 10 connections, and 1000 events are queued for transmission. +As each connection finishes transmitting an event, it becomes available again and returns to the pool so the handler can use it to send the next event in the queue. + +TCP stream handlers will reuse the available connections as long as they can rather than requiring a new connection for every event, which increases event throughput. +In addition to providing a persistent TCP connection to transmit Sensu observation events to a remote data storage service, TCP stream handlers allow you to use transport layer security (TLS) for secure data transmission. + +TCP stream handlers are commercial resources available for use in [pipeline definitions][2]. + +## TCP stream handler example + +This example shows a TCP stream handler resource definition configured to use TLS: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: TCPStreamHandler +api_version: pipeline/v1 +metadata: + name: logstash +spec: + address: 127.0.0.1:4242 + tls_ca_cert_file: "/path/to/tls/ca.pem" + tls_cert_file: "/path/to/tls/cert.pem" + tls_key_file: "/path/to/tls/key.pem" + max_connections: 10 + min_reconnect_delay: 10ms + max_reconnect_delay: 10s +{{< /code >}} + +{{< code json >}} +{ + "type": "TCPStreamHandler", + "api_version": "pipeline/v1", + "metadata": { + "name": "logstash" + }, + "spec": { + "address": "127.0.0.1:4242", + "tls_ca_cert_file": "/path/to/tls/ca.pem", + "tls_cert_file": "/path/to/tls/cert.pem", + "tls_key_file": "/path/to/tls/key.pem", + "max_connections": 10, + "min_reconnect_delay": "10ms", + "max_reconnect_delay": "10s" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Use TCP stream handlers + +TCP stream handlers are commercial resources and are available for use **only** in [pipelines][2]. + +{{% notice note %}} +**NOTE**: TCP stream handlers **are not** used by listing the handler name in the check [handlers attribute](../../observe-schedule/checks/#handlers-array). +{{% /notice %}} + +To use a TCP stream handler, list it as the [handler][11] in a [pipeline][2] definition. +For example, this pipeline definition uses the [logstash example][12] along with the built-in [is_incident][13] event filter: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Pipeline +api_version: core/v2 +metadata: + name: tcp_logging_workflows +spec: + workflows: + - name: log_all_incidents + filters: + - name: is_incident + type: EventFilter + api_version: core/v2 + handler: + name: logstash + type: TCPStreamHandler + api_version: pipeline/v1 +{{< /code >}} + +{{< code json >}} +{ + "type": "Pipeline", + "api_version": "core/v2", + "metadata": { + "name": "tcp_logging_workflows" + }, + "spec": { + "workflows": [ + { + "name": "log_all_incidents", + "filters": [ + { + "name": "is_incident", + "type": "EventFilter", + "api_version": "core/v2" + } + ], + "handler": { + "name": "logstash", + "type": "TCPStreamHandler", + "api_version": "pipeline/v1" + } + } + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## TCP stream handler specification + +### Top-level attributes + +type | +-------------|------ +description | Top-level attribute that specifies the [`sensuctl create`][4] resource type. TCP stream handlers should always be type `TCPStreamHandler`. +required | Required for TCP stream handler definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][4]. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +type: TCPStreamHandler +{{< /code >}} +{{< code json >}} +{ + "type": "TCPStreamHandler" +} +{{< /code >}} +{{< /language-toggle >}} + +api_version | +-------------|------ +description | Top-level attribute that specifies the Sensu API group and version. For TCP stream handlers in this version of Sensu, the `api_version` should always be `pipeline/v1`. +required | Required for TCP stream handler definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][4]. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +api_version: pipeline/v1 +{{< /code >}} +{{< code json >}} +{ + "api_version": "pipeline/v1" +} +{{< /code >}} +{{< /language-toggle >}} + +metadata | +-------------|------ +description | Top-level collection of metadata about the TCP stream handler that includes `name`, `namespace`, and `created_by` as well as custom `labels` and `annotations`. The `metadata` map is always at the top level of the handler definition. This means that in `wrapped-json` and `yaml` formats, the `metadata` scope occurs outside the `spec` scope. Read [metadata attributes][8] for details. +required | Required for TCP stream handler definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][4]. +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +metadata: + name: logstash + namespace: default + created_by: admin + labels: + environment: development + region: us-west-2 + annotations: + managed-by: ops +{{< /code >}} +{{< code json >}} +{ + "metadata": { + "name": "logstash", + "namespace": "default", + "created_by": "admin", + "labels": { + "environment": "development", + "region": "us-west-2" + }, + "annotations": { + "managed-by": "ops" + } + } +} +{{< /code >}} +{{< /language-toggle >}} + +spec | +-------------|------ +description | Top-level map that includes the TCP stream handler [spec attributes][5]. +required | Required for TCP stream handler definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][4]. +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +spec: + address: 127.0.0.1:4242 + tls_ca_cert_file: "/path/to/tls/ca.pem" + tls_cert_file: "/path/to/tls/cert.pem" + tls_key_file: "/path/to/tls/key.pem" + max_connections: 10 + min_reconnect_delay: 10ms + max_reconnect_delay: 10s +{{< /code >}} +{{< code json >}} +{ + "spec": { + "address": "127.0.0.1:4242", + "tls_ca_cert_file": "/path/to/tls/ca.pem", + "tls_cert_file": "/path/to/tls/cert.pem", + "tls_key_file": "/path/to/tls/key.pem", + "max_connections": 10, + "min_reconnect_delay": "10ms", + "max_reconnect_delay": "10s" + } +} +{{< /code >}} +{{< /language-toggle >}} + +### Metadata attributes + +| name | | +-------------|------ +description | Unique string used to identify the TCP stream handler. TCP stream handler names cannot contain special characters or spaces (validated with Go regex [`\A[\w\.\-]+\z`][18]). Each TCP stream handler must have a unique name within its namespace. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +name: logstash +{{< /code >}} +{{< code json >}} +{ + "name": "logstash" +} +{{< /code >}} +{{< /language-toggle >}} + +| namespace | | +-------------|------ +description | Sensu [RBAC namespace][9] that the TCP stream handler belongs to. +required | false +type | String +default | `default` +example | {{< language-toggle >}} +{{< code yml >}} +namespace: default +{{< /code >}} +{{< code json >}} +{ + "namespace": "default" +} +{{< /code >}} +{{< /language-toggle >}} + +| created_by | | +-------------|------ +description | Username of the Sensu user who created the TCP stream handler or last updated the TCP stream handler. Sensu automatically populates the `created_by` field when the TCP stream handler is created or updated. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +created_by: admin +{{< /code >}} +{{< code json >}} +{ + "created_by": "admin" +} +{{< /code >}} +{{< /language-toggle >}} + +| labels | | +-------------|------ +description | Custom attributes to include with observation event data that you can use for response and web UI view filtering.

    If you include labels in your event data, you can filter [API responses][15], [sensuctl responses][16], and [web UI views][25] based on them. In other words, labels allow you to create meaningful groupings for your data.

    Limit labels to metadata you need to use for response filtering. For complex, non-identifying metadata that you will *not* need to use in response filtering, use annotations rather than labels. +required | false +type | Map of key-value pairs. Keys can contain only letters, numbers, and underscores and must start with a letter. Values can be any valid UTF-8 string. +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +labels: + environment: development + region: us-west-2 +{{< /code >}} +{{< code json >}} +{ + "labels": { + "environment": "development", + "region": "us-west-2" + } +} +{{< /code >}} +{{< /language-toggle >}} + +| annotations | | +-------------|------ +description | Non-identifying metadata to include with observation event data that you can access with [event filters][24]. You can use annotations to add data that's meaningful to people or external tools that interact with Sensu.

    In contrast to labels, you cannot use annotations in [API response filtering][15], [sensuctl response filtering][16], or [web UI views][28]. +required | false +type | Map of key-value pairs. Keys and values can be any valid UTF-8 string. +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +annotations: + managed-by: ops +{{< /code >}} +{{< code json >}} +{ + "annotations": { + "managed-by": "ops" + } +} +{{< /code >}} +{{< /language-toggle >}} + +### Spec attributes + +address | +-------------|------ +description | The hostname:port combination the TCP stream handler should connect to. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +address: 127.0.0.1:4242 +{{< /code >}} +{{< code json >}} +{ + "address": "127.0.0.1:4242" +} +{{< /code >}} +{{< /language-toggle >}} + +tls_ca_cert_file | +-------------|------ +description | Path to the PEM-format CA certificate to use for TLS client authentication. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +tls_ca_cert_file: "/path/to/tls/ca.pem" +{{< /code >}} +{{< code json >}} +{ + "tls_ca_cert_file": "/path/to/tls/ca.pem" +} +{{< /code >}} +{{< /language-toggle >}} + +tls_cert_file | +-------------|------ +description | Path to the PEM-format certificate to use for TLS client authentication. This certificate and its corresponding key are required for secure client communication. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +tls_cert_file: "/path/to/tls/cert.pem" +{{< /code >}} +{{< code json >}} +{ + "tls_cert_file": "/path/to/tls/cert.pem" +} +{{< /code >}} +{{< /language-toggle >}} + +tls_key_file | +------------|------ +description | Path to the PEM-format key file associated with the tls_cert_file to use for TLS client authentication. This key and its corresponding certificate are required for secure client communication. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +tls_key_file: "/path/to/tls/key.pem" +{{< /code >}} +{{< code json >}} +{ + "tls_key_file": "/path/to/tls/key.pem" +} +{{< /code >}} +{{< /language-toggle >}} + +max_connections | +-------------|------ +description | Maximum number of connections to keep alive in the connection pool. If set to `0`, connection pooling is disabled. +required | true +type | Integer +example | {{< language-toggle >}} +{{< code yml >}} +max_connections: 10 +{{< /code >}} +{{< code json >}} +{ + "max_connections": 10 +} +{{< /code >}} +{{< /language-toggle >}} + +max_reconnect_delay | +-------------|------ +description | Maximum time to wait while retrying a broken connection. In seconds (`s`) or milliseconds (`ms`). +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +max_reconnect_delay: 10s +{{< /code >}} +{{< code json >}} +{ + "max_reconnect_delay": "10s" +} +{{< /code >}} +{{< /language-toggle >}} + +min_reconnect_delay | +-------------|------ +description | Minimum time to wait while retrying a broken connection. In seconds (`s`) or milliseconds (`ms`). +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +min_reconnect_delay: 10ms +{{< /code >}} +{{< code json >}} +{ + "min_reconnect_delay": "10ms" +} +{{< /code >}} +{{< /language-toggle >}} + + +[1]: ../handlers/#tcpudp-handlers +[2]: ../pipelines/ +[4]: ../../../sensuctl/create-manage-resources/#create-resources +[5]: #spec-attributes +[8]: #metadata-attributes +[9]: ../../../operations/control-access/namespaces/ +[11]: ../pipelines/#handlers-pipeline +[12]: #tcp-stream-handler-example +[13]: ../../observe-filter/filters/#built-in-filter-is_incident +[15]: ../../../api/#response-filtering +[16]: ../../../sensuctl/filter-responses/ +[18]: https://regex101.com/r/zo9mQU/2 +[22]: ../ +[24]: ../../observe-filter/filters/ +[25]: ../../../web-ui/search#search-for-labels +[28]: ../../../web-ui/search/ +[29]: ../../../observability-pipeline/ diff --git a/content/sensu-go/6.12/observability-pipeline/observe-schedule/_index.md b/content/sensu-go/6.12/observability-pipeline/observe-schedule/_index.md new file mode 100644 index 0000000000..870c6da8b6 --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-schedule/_index.md @@ -0,0 +1,160 @@ +--- +title: "Schedule observability data collection" +linkTitle: "Schedule" +description: "Learn how Sensu uses the publish/subscribe pattern of communication to schedule checks for agents and publish check execution requests to entities." +product: "Sensu Go" +version: "6.12" +weight: 30 +layout: "single" +toc: true +menu: + sensu-go-6.12: + parent: observability-pipeline + identifier: observe-schedule +--- + + + + +** or click any element in the pipeline to jump to it.** + +Sensu's schedule function is based on subscriptions: transport topics to which the Sensu backend publishes check requests. +The subscriptions you specify in your Sensu agent definition determine which checks the agent will execute. +The Sensu backend schedules checks, publishes check execution requests to entities, and processes the observation data (events) it receives from the agent. + +## Agent and backend + +The Sensu agent is a lightweight process that runs on the infrastructure components you want to monitor and observe. +The agent registers with the Sensu backend as an entity with `type: "agent"`. +Agent entities are responsible for creating [status and metrics events][6] to send to the [backend event pipeline][2]. + +The Sensu backend includes an integrated structure for scheduling [checks][15] using subscriptions and an event pipeline that applies [event filters][16], [mutators][17], and [handlers][18], an embedded [etcd][10] datastore for storing configuration and state, and the Sensu [API][4], Sensu [web UI][5], and [sensuctl][19] command line tool. + +The Sensu agent is available for Linux, macOS, and Windows. +The Sensu backend is available for Debian- and RHEL-family distributions of Linux. +Learn more in the [agent][11] and [backend][2] references. + +Follow the [installation guide][1] to install the agent and backend. + +## Subscriptions + +[Subscriptions][12] are at the core of Sensu's [publish/subscribe pattern of communication][13]: subscriptions are transport topics to which the Sensu backend publishes check requests. +Sensu entities become subscribers to these topics via their individual `subscriptions` attribute. + +Each Sensu agent's defined set of subscriptions determine which [checks][15] the agent will execute. +Agent subscriptions allow Sensu to request check executions on a group of systems at a time instead of a traditional 1:1 mapping of configured hosts to monitoring checks. + +In each check's definition, you can specify which subscriptions should run the check. +At the same time, your entities are "subscribed" to these subscriptions. +Subscriptions make sure your entities automatically run the appropriate checks for their functionality. + +The following example shows the resource definition for a check with the `system` and `linux` subscriptions. +This check would run on any entities whose definitions also specify the `system` or `linux` subscriptions. + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: check-cpu +spec: + check_hooks: null + command: check-cpu-usage -w 75 -c 90 + env_vars: null + handlers: + - slack + high_flap_threshold: 0 + interval: 60 + low_flap_threshold: 0 + output_metric_format: "" + output_metric_handlers: null + proxy_entity_name: "" + publish: true + round_robin: false + runtime_assets: + - check-cpu-usage + secrets: null + stdin: false + subdue: null + subscriptions: + - system + - linux + timeout: 0 + ttl: 0 +{{< /code >}} + +{{< code json >}} +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "check-cpu" + }, + "spec": { + "check_hooks": null, + "command": "check-cpu-usage -w 75 -c 90", + "env_vars": null, + "handlers": [ + "slack" + ], + "high_flap_threshold": 0, + "interval": 60, + "low_flap_threshold": 0, + "output_metric_format": "", + "output_metric_handlers": null, + "proxy_entity_name": "", + "publish": true, + "round_robin": false, + "runtime_assets": [ + "check-cpu-usage" + ], + "secrets": null, + "stdin": false, + "subdue": null, + "subscriptions": [ + "system" + ], + "timeout": 0, + "ttl": 0 + } +} +{{< /code >}} + +{{< /language-toggle >}} + +Subscriptions typically correspond to a specific role or responsibility. +For example, you might add all the checks you want to run on your database entities to a `database` subscription. +Rather than specifying these checks individually for every database you are monitoring, you add the `database` subscription to your database entities and they run the desired checks automatically. + +Read the [subscriptions reference][12] to learn more. + +## Communication between the agent and backend + +The Sensu agent uses [WebSocket][7] (ws) protocol to send and receive JSON messages with the Sensu backend. +For optimal network throughput, agents will attempt to negotiate the use of [Protobuf][9] serialization when communicating with a Sensu backend that supports it. +This communication is via clear text by default. + +Follow [Secure Sensu][8] to configure the backend and agent for WebSocket Secure (wss) encrypted communication. + + +[1]: ../../operations/deploy-sensu/install-sensu/ +[2]: backend/ +[3]: ../observe-entities/ +[4]: ../../api/ +[5]: ../../web-ui/ +[6]: ../observe-events/ +[7]: https://en.m.wikipedia.org/wiki/WebSocket +[8]: ../../operations/deploy-sensu/secure-sensu/ +[9]: https://en.m.wikipedia.org/wiki/Protocol_Buffers +[10]: https://etcd.io/docs +[11]: agent/ +[12]: subscriptions/ +[13]: https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern +[14]: agent/#create-observability-events-using-service-checks +[15]: checks/ +[16]: ../observe-filter/filters/ +[17]: ../observe-transform/mutators/ +[18]: ../observe-process/handlers/ +[19]: ../../sensuctl/ diff --git a/content/sensu-go/6.12/observability-pipeline/observe-schedule/agent.md b/content/sensu-go/6.12/observability-pipeline/observe-schedule/agent.md new file mode 100644 index 0000000000..c860d972de --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-schedule/agent.md @@ -0,0 +1,2120 @@ +--- +title: "Agent reference" +linkTitle: "Agent Reference" +reference_title: "Agent" +type: "reference" +description: "Read this reference to learn how Sensu's agent runs as a lightweight client on infrastructure components you want to monitor and creates observability events." +weight: 10 +version: "6.12" +product: "Sensu Go" +platformContent: true +platforms: ["Linux", "Windows"] +menu: + sensu-go-6.12: + parent: observe-schedule +--- + +[Example Sensu agent configuration file](../../../files/agent.yml) (download) + +The Sensu agent is a lightweight client that runs on the infrastructure components you want to monitor. +Agents register with the Sensu backend as [entities][3] with `type: "agent"`. +Agent entities are responsible for creating [check and metrics events][7] to send to the [backend event pipeline][2]. + +The Sensu agent is available for Linux, macOS, and Windows. +For Windows operating systems, the Sensu agent uses `cmd.exe` for the execution environment. +For all other operating systems, the Sensu agent uses the Bourne shell (sh). + +Read the [installation guide][1] to install the agent. + +## Agent authentication + +The Sensu agent authenticates to the Sensu backend via [WebSocket][45] transport by either built-in basic authentication (username and password) or mutual transport layer security (mTLS) authentication. + +### Username and password authentication + +The default mechanism for agent authentication is [built-in basic authentication][59] with username and password. +The Sensu agent uses username and password authentication unless mTLS authentication has been explicitly configured. + +For username and password authentication, sensu-agent joins the username and password with a colon and encodes them as a Base64 value. +Sensu provides the encoded string as the value of the `Authorization` HTTP header — for example, `Authorization: Basic YWdlbnQ6UEBzc3cwcmQh` — to authenticate to the Sensu backend. + +When using username and password authentication, sensu-agent also sends the following HTTP headers in requests to the backend: + +- `Sensu-User`: the username in plaintext +- `Sensu-AgentName`: the agent's configured name in plaintext +- `Sensu-Subscriptions`: the agent's subscriptions in a comma-separated plaintext list +- `Sensu-Namespace`: the agent's configured namespace in plaintext + +### mTLS authentication + +When mTLS is configured for both the Sensu agent and backend, the agent uses mTLS authentication instead of the default username and password authentication. + +Sensu backends that are configured for mTLS authentication will no longer accept agent authentication via username and password. +Agents that are configured to use mTLS authentication cannot authenticate with the backend unless the backend is configured for mTLS. + +To configure the agent and backend for mTLS authentication: + +- In the backend configuration, specify valid certificate and key files as values for the `agent-auth-cert-file` and `agent-auth-key-file` parameters (e.g. `backend-1.pem` and `backend-1-key.pem`, respectively). +- In the agent configuration, specify valid certificate and key files as values for the `cert-file` and `key-file` parameters (e.g. `agent.pem` and `agent-key.pem`, respectively). + +{{% notice note %}} +**NOTE**: For detailed information about the certificates and keys required for mTLS authentication, read [Generate certificates for your Sensu installation](../../../operations/deploy-sensu/generate-certificates/). +For information about using the certificates and keys to secure your configuration, read [Secure Sensu](../../../operations/deploy-sensu/secure-sensu/). +{{% /notice %}} + +The agent and backend will compare the provided certificates with the trusted CA certificate either in the system trust store or specified explicitly as the `agent-auth-trusted-ca-file` in the backend configuration and `trusted-ca-file` in the agent configuration. + +When using mTLS authentication, sensu-agent sends the following HTTP headers in requests to the backend: + +- `Sensu-AgentName`: the agent's configured name in plaintext +- `Sensu-Subscriptions`: the agent's subscriptions in a comma-separated, plaintext list +- `Sensu-Namespace`: the agent's configured namespace in plaintext + +If the Sensu agent is configured for mTLS authentication, it will not send the `Authorization` HTTP header. + +#### Certificate bundles or chains + +The Sensu agent supports all types of certificate bundles (or chains) as long as the agent (or leaf) certificate is the *first* certificate in the bundle. +This is because the Go standard library assumes that the first certificate listed in the PEM file is the leaf certificate — the certificate that the program will use to show its own identity. + +If you send the leaf certificate alone instead of sending the whole bundle with the leaf certificate first, you will receive a `certificate not signed by trusted authority` error. +You must present the whole chain to the remote so it can determine whether it trusts the presented certificate through the chain. + +#### Certificate revocation check + +The Sensu backend checks certificate revocation list (CRL) and Online Certificate Status Protocol (OCSP) endpoints for agent mTLS, etcd client, and etcd peer connections whose remote sides present X.509 certificates that provide CRL and OCSP revocation information. + +## Communication between the agent and backend + +The Sensu agent uses [WebSocket][45] (ws) protocol to send and receive JSON messages with the Sensu backend. +For optimal network throughput, agents will attempt to negotiate the use of [Protobuf][47] serialization when communicating with a Sensu backend that supports it. +This communication is via clear text by default. + +Follow [Secure Sensu][46] to configure the backend and agent for WebSocket Secure (wss) encrypted communication. + +{{% notice note %}} +**NOTE**: For information about agent transport status, use the [/health API](../../../api/other/health/#get-health-data-for-your-agent-transport). +{{% /notice %}} + +## Connection failure + +Although connection failure may be due to socket errors like unexpectedly closed connections and TLS handshake failures, the Sensu agent generally keeps retrying connections to each URL in the `backend-url` list until it is successfully connected to a backend URL or you stop the process. + +When you start up a Sensu agent configured with multiple `backend-url` values, the agent shuffles the `backend-url` list and attempts to connect to the first URL in the shuffled list. +If the agent cannot establish a WebSocket connection with the first URL within the number of seconds specified for the [`backend-handshake-timeout`][43], the agent abandons the connection attempt and tries the next URL in the shuffled list. + +When the agent establishes a WebSocket connection with a backend URL within the `backend-handshake-timeout` period, the agent sends a heartbeat message to the backend at the specified [`backend-heartbeat-interval`][34]. +For every heartbeat the agent sends, the agent expects the connected backend to send a heartbeat response within the number of seconds specified for the `backend-heartbeat-timeout`. +If the connected backend does not respond within the `backend-heartbeat-timeout` period, the agent closes the connection and attempts to connect to the next backend URL in the shuffled list. + +The agent iterates through the shuffled `backend-url` list until it successfully establishes a WebSocket connection with a backend, returning to the first URL if it fails to connect with the last URL in the list. + +{{% notice note %}} +**NOTE**: Sensu's WebSocket connection heartbeat message and [keepalive monitoring](#keepalive-monitoring) mechanism are different, although they have similar purposes.

    +The `backend-heartbeat-interval` and `backend-heartbeat-timeout` are specifically configured for the WebSocket connection heartbeat message the agent sends when it connects to a backend URL.

    +Keepalive monitoring is more fluid — it permits agents to reconnect any number of times within the configured timeout. +As long as the agent can successfully send one event to any backend within the timeout, the keepalive logic is satisfied. +{{% /notice %}} + +## Synchronize time between agents and the backend + +System clocks between agents and the backend should be synchronized to a central NTP server. +If system time is out of sync, it may cause issues with keepalive, metric, and check alerts. + +## Agent connection to a cluster + +Agents can connect to a Sensu cluster by specifying any Sensu backend URL in the cluster in the [`backend-url`][16] configuration option. + +For more information about clustering, read [Backend datastore configuration][35] and [Run a Sensu cluster][36]. + +## Keepalive monitoring + +Sensu keepalives are the heartbeat mechanism used to ensure that all registered agents are operational and able to reach the [Sensu backend][2]. +Sensu agents publish keepalive events containing [entity][3] configuration data to the Sensu backend according to the interval specified by the [`keepalive-interval`][4] configuration option. +All Sensu agent data provided in keepalive events is stored in the agent registry and used to add context to Sensu events and detect Sensu agents in an unhealthy state. + +If a Sensu agent fails to send keepalive events over the period specified by the [`keepalive-critical-timeout`][4] configuration option, the Sensu backend creates a keepalive **critical** alert in the Sensu web UI. +The `keepalive-critical-timeout` is set to `0` (disabled) by default to help ensure that it will not interfere with your `keepalive-warning-timeout` setting. + +If a Sensu agent fails to send keepalive events over the period specified by the [`keepalive-warning-timeout`][58] configuration option, the Sensu backend creates a keepalive **warning** alert in the Sensu web UI. +The value you specify for `keepalive-warning-timeout` must be lower than the value you specify for `keepalive-critical-timeout`. + +{{% notice note %}} +**NOTE**: If you set the [`deregister` configuration option](#ephemeral-agent-configuration) to `true`, when a Sensu agent process stops, the Sensu backend will deregister the corresponding entity.

    +Deregistration prevents and clears alerts for failing keepalives for agent entities — the backend does not distinguish between intentional shutdown and failure. +As a result, if you set `deregister` to `true` and an agent process stops for any reason, you will not receive alerts for keepalive events in the web UI.

    +If you want to receive alerts for failing keepalives, set the [deregister configuration option](#ephemeral-agent-configuration) to `false`. +{{% /notice %}} + +You can use keepalives to identify unhealthy systems and network partitions, send notifications, trigger auto-remediation, and [automatically register and deregister agent entities][11], among other useful actions. +The agent maps [`keepalive-critical-timeout`][4] and [`keepalive-warning-timeout`][58] values to certain event check attributes, so you can also [create time-based event filters][57] to reduce alert fatigue for agent keepalive events. + +{{% notice note %}} +**NOTE**: Automatic keepalive monitoring is not supported for [proxy entities](../../observe-entities/#proxy-entities) because they cannot run a Sensu agent. +Use the [core/v2/events API](../../../api/core/events/) to send manual keepalive events for proxy entities. +{{% /notice %}} + +### Process keepalive events + +Process keepalive events with a [pipeline][66] or [handler][67]. + +#### Keepalive pipelines + +Use the [`keepalive-pipelines`][64] configuration option to send keepalive events to any [pipeline][63] you have configured. + +To specify pipelines for the `keepalive-pipelines` option, use the [fully qualified name][65] for pipelines (`core/v2.Pipeline`) plus the pipeline name (e.g. `slack` or `store-keepalives`). +For example: + +{{< language-toggle >}} + +{{< code shell "Command Line" >}} +sensu-agent start --keepalive-pipelines core/v2.Pipeline.slack,core/v2.Pipeline.store-keepalives +{{< /code >}} + +{{< code yml "/etc/sensu/agent.yml" >}} +keepalive-pipelines: +- core/v2.Pipeline.slack +- core/v2.Pipeline.store-keepalives +{{< /code >}} + +{{< /language-toggle >}} + +If you do not specify a pipeline with the `keepalive-pipelines` option, the Sensu backend will use the default `keepalive` handler and create an event in sensuctl and the Sensu web UI for keepalives. + +#### Keepalive handlers + +You can use a keepalive handler to connect keepalive events to your monitoring workflows. +Sensu looks for an [event handler][8] named `keepalive` and automatically uses it to process keepalive events. + +Suppose you want to receive Slack notifications for keepalive alerts, and you already have a [Slack handler set up to process events][40]. +To process keepalive events using the Slack handler, create a handler set named `keepalive` and add the `slack` handler to the `handlers` array. +The resulting `keepalive` handler set configuration looks like this: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Handler +api_version: core/v2 +metadata: + name: keepalive +spec: + handlers: + - slack + type: set +{{< /code >}} + +{{< code json >}} +{ + "type": "Handler", + "api_version": "core/v2", + "metadata" : { + "name": "keepalive" + }, + "spec": { + "type": "set", + "handlers": [ + "slack" + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +You can also use the [`keepalive-handlers`][53] configuration option to send keepalive events to any handler you have configured. +If you do not specify a keepalive handler with the `keepalive-handlers` option, the Sensu backend will use the default `keepalive` handler and create an event in sensuctl and the Sensu web UI. + +## Create observability events using service checks + +The Sensu backend coordinates check execution for you by comparing the subscriptions you specify in your checks and entities to determine which entities should receive execution requests for a given check. + +Sensu uses the [publish/subscribe pattern of communication][15], which allows automated registration and deregistration of ephemeral systems. +At the core of this model are Sensu [subscriptions][28], which you specify in checks and entities to determine which entities should receive execution requests for a given check. +Subscriptions often correspond with the roles and responsibilities assigned to the entity, such as `webserver` or `database`. + +Subscriptions determine which [checks][14] the agent will execute. +For an agent to execute a check, at least one [entity][3] must include a subscription that matches a subscription in the check definition. +Read the [subscriptions reference][28] for more information. + +After receiving a check request from the Sensu backend, the agent: + +1. Applies any [tokens][27] that match attribute values in the check definition. +2. Fetches [dynamic runtime assets][29] and stores them in its local cache. + + By default, agents cache dynamic runtime asset data at `/var/cache/sensu/sensu-agent` (Linux) or `C:\ProgramData\sensu\cache\sensu-agent` (Windows). + To specify a different cache location, use the [`cache-dir`][30] configuration attribute. + +3. Executes the [check command][14]. +4. Executes any [hooks][31] specified by the check based on the exit status. +5. Creates an [event][7] that contains information about the applicable entity, check, and metric. + +The Sensu backend then processes the event by applying event filters, mutators, and handlers. + +### Proxy entities + +Proxy entities allow Sensu to monitor external resources on systems or devices where a Sensu agent cannot be installed, like a network switch. + +The [Sensu backend][2] stores proxy entity definitions (unlike agent entities, which the agent stores). +When the backend requests a check that includes a [`proxy_entity_name`][32], the agent includes the provided entity information in the observation data in events in place of the agent entity data. + +Read the [entities reference][3] and [Monitor external resources][33] for more information about monitoring proxy entities. + +## Create observability events using the agent API + +The Sensu agent API allows external sources to send monitoring data to Sensu without requiring the external sources to know anything about Sensu's internal implementation. +The agent API listens on the address and port specified with the agent [API configuration options][18]. + +The agent API supports only unsecured HTTP requests (no HTTPS). +Requests for unknown endpoints will result in an `HTTP 404 Not Found` response. + +### `/events` (POST) + +The agent API provides HTTP POST access to publish [observability events][7] to the Sensu backend via the `/events` endpoint. + +The agent places events created via the agent API `/events` endpoint into a queue stored on disk. +In case of a loss of connection with the backend or agent shutdown, the agent preserves queued event data. +When the connection is reestablished, the agent sends the queued events to the backend. + +The agent API `/events` endpoint uses a configurable burst limit and rate limit for relaying events to the backend. +Read [API configuration](#api-configuration) to configure the `events-burst-limit` and `events-rate-limit` options. + +#### Example POST request to events endpoint + +The following example submits an HTTP POST request to the agent API `/events` endpoint. +The request creates an event for a check named `check-mysql-status` with the output `could not connect to mysql` and a status of `1` (warning). +The agent responds with an `HTTP 202 Accepted` response to indicate that the event has been added to the queue to be sent to the backend. + +In this example, the event will be processed according to an `incident_alerts` [pipeline][63]. + +{{% notice note %}} +**NOTE**: For HTTP POST requests to the agent API `/events` endpoint, check-specific [spec attributes](../checks/#spec-attributes) are not required. +If you do want to include spec attributes, list them as individual [top-level attributes](../checks/#top-level-attributes) within the event's `check` scope. +{{% /notice %}} + +{{< code shell >}} +curl -X POST \ +-H 'Content-Type: application/json' \ +-d '{ + "check": { + "metadata": { + "name": "check-mysql-status" + }, + "status": 1, + "output": "could not connect to mysql" + }, + "pipelines": [ + { + "api_version": "core/v2", + "type": "Pipeline", + "name": "incident_alerts" + } + ] +}' \ +http://127.0.0.1:3031/events +{{< /code >}} + +{{% notice protip %}} +**PRO TIP**: To use the agent API `/events` endpoint to create proxy entities, include a `proxy_entity_name` attribute within the `check` scope. +{{% /notice %}} + +#### Detect silent failures + +You can use the Sensu agent API in combination with the check [time-to-live (TTL) attribute][44] to detect silent failures. +This creates what's commonly referred to as a ["dead man's switch"][20]. + +With check TTLs, Sensu can set an expectation that a Sensu agent will publish additional events for a check within the period of time specified by the TTL attribute. +If a Sensu agent fails to publish an event before the check TTL expires, the Sensu backend creates an event with a status of `1` (warning) to indicate the expected event was not received. +For more information about check TTLs, read the [checks reference][44]. + +If you use the check TTL attribute along with the Sensu agent API to enable tasks that run outside of Sensu's check scheduling to emit events, these events create a dead man's switch: if the task fails for any reason, the lack of an "all clear" event from the task will notify operators of the silent failure, which might otherwise be missed. +If an external source sends an event with a check TTL to the Sensu agent API, Sensu expects another event from the same external source before the TTL expires. + +Here's an example of external event input via the Sensu agent API that uses a check TTL to create a dead man's switch for MySQL backups. +Assume that a MySQL backup script runs periodically, and you expect the job to take a little less than 7 hours to complete. + +- If the job completes successfully, you want a record of it, but you don't need to receive an alert. +- If the job fails or continues running longer than the expected 7 hours, you do need to receive an alert. + +The script can send an event that tells the Sensu backend to expect an additional event with the same name within 7 hours of the first event: + +{{< code shell >}} +curl -X POST \ +-H 'Content-Type: application/json' \ +-d '{ + "check": { + "metadata": { + "name": "mysql-backup-job" + }, + "status": 0, + "output": "mysql backup initiated", + "ttl": 25200 + } +}' \ +http://127.0.0.1:3031/events +{{< /code >}} + +When the script submitted this initial event to the agent API, you recorded in the Sensu backend that your script started. +You also configured the dead man's switch by including the `ttl` attribute, so you'll receive an alert if the job fails or runs for too long. +Although it is possible for your script to handle errors gracefully and emit additional observability events, this approach allows you to worry less about handling every possible error case. +A lack of additional events before the 7-hour period elapses results in an alert. + +If your backup script runs successfully, it can send an additional event without the TTL attribute, which removes the dead man's switch: + +{{< code shell >}} +curl -X POST \ +-H 'Content-Type: application/json' \ +-d '{ + "check": { + "metadata": { + "name": "mysql-backup-job" + }, + "status": 0, + "output": "mysql backup ran successfully!" + } +}' \ +http://127.0.0.1:3031/events +{{< /code >}} + +Omitting the TTL attribute from this event also removes the dead man's switch being monitored by the Sensu backend. +This effectively sounds the "all clear" for this iteration of the task. + +#### API specification {#events-post-specification} + +/events (POST) | +-------------------|------ +description | Accepts JSON [event data][7] and passes the event to the Sensu backend event pipeline for processing. +example url | http://hostname:3031/events +payload example | {{< code json >}}{ + "check": { + "metadata": { + "name": "check-mysql-status" + }, + "status": 1, + "output": "could not connect to mysql" + } +}{{< /code >}} +payload attributes |
      Required:
    • `check`: All check data must be within the `check` scope
    • `metadata`: The `check` scope must contain a `metadata` scope
    • `name`: The `metadata` scope must contain the `name` attribute with a string that represents the name of the monitoring check
      Optional:
    • Any other attributes supported by the [Sensu check specification][14]
    +response codes |
    • **Success**: 202 (Accepted)
    • **Malformed**: 400 (Bad Request)
    • **Error**: 500 (Internal Server Error)
    + +### `/healthz` (GET) + +The agent API `/healthz` endpoint provides HTTP GET access to the status of the Sensu agent via the agent API. + +#### Example {#healthz-get-example} + +In the following example, an HTTP GET request is submitted to the agent API `/healthz` endpoint: + +{{< code shell >}} +curl http://127.0.0.1:3031/healthz +{{< /code >}} + +The request results in a healthy response: + +{{< code text >}} +ok +{{< /code >}} + +#### API specification {#healthz-get-specification} + +/healthz (GET) | +----------------|------ +description | Returns the agent status:
    - `ok` if the agent is active and connected to a Sensu backend.
    - `sensu backend unavailable` if the agent cannot connect to a backend. +example url | http://hostname:3031/healthz + +## Create observability events using the StatsD listener + +Sensu agents include a listener to send [StatsD][21] metrics to the event pipeline. +By default, Sensu agents listen on UDP socket 8125 for messages that follow the [StatsD line protocol][21] and send metric events for handling by the Sensu backend. + +For example, you can use the [Netcat][19] utility to send metrics to the StatsD listener: + +{{< code shell >}} +echo 'abc.def.g:10|c' | nc -w1 -u localhost 8125 +{{< /code >}} + +Sensu does not store metrics received through the StatsD listener, so it's important to configure [event handlers][8]. + +### StatsD line protocol + +The Sensu StatsD listener accepts messages that are formatted according to the StatsD line protocol: + +{{< code shell >}} +:| +{{< /code >}} + +For more information about StatsD, read the [StatsD documentation][21]. + +### Configure the StatsD listener + +To configure the StatsD listener, specify the [`statsd-event-handlers`][22] configuration option in the [agent configuration][24] and start the agent. +For example, to start an agent that sends StatsD metrics to InfluxDB, run: + +{{< code shell >}} +sensu-agent --statsd-event-handlers influx-db +{{< /code >}} + +Use the [StatsD configuration options][22] to change the default settings for the StatsD listener address, port, and [flush interval][23]. +For example, to start an agent with a customized address and flush interval, run: + +{{< code shell >}} +sensu-agent --statsd-event-handlers influx-db --statsd-flush-interval 1 --statsd-metrics-host 123.4.5.11 --statsd-metrics-port 8125 +{{< /code >}} + +## Create observability events using the agent TCP and UDP sockets + +{{% notice note %}} +**NOTE**: The agent TCP and UDP sockets are deprecated in favor of the [agent API](#create-observability-events-using-the-agent-api). +{{% /notice %}} + +Sensu agents listen for external monitoring data using TCP and UDP sockets. +The agent sockets accept JSON event data and pass events to the Sensu backend event pipeline for processing. +The TCP and UDP sockets listen on the address and port specified by the [socket configuration options][17]. + +### Use the TCP socket + +This example demonstrates external monitoring data input via the Sensu agent TCP socket. +The example uses Bash's built-in `/dev/tcp` file to communicate with the Sensu agent socket: + +{{< code shell >}} +echo '{"name": "check-mysql-status", "status": 1, "output": "error!"}' > /dev/tcp/localhost/3030 +{{< /code >}} + +You can also use the [Netcat][19] utility to send monitoring data to the agent socket: + +{{< code shell >}} +echo '{"name": "check-mysql-status", "status": 1, "output": "error!"}' | nc localhost 3030 +{{< /code >}} + +### Use the UDP socket + +This example demonstrates external monitoring data input via the Sensu agent UDP socket. +The example uses Bash's built-in `/dev/udp` file to communicate with the Sensu agent socket: + +{{< code shell >}} +echo '{"name": "check-mysql-status", "status": 1, "output": "error!"}' > /dev/udp/127.0.0.1/3030 +{{< /code >}} + +You can also use the [Netcat][19] utility to send monitoring data to the agent socket: + +{{< code shell >}} +echo '{"name": "check-mysql-status", "status": 1, "output": "error!"}' | nc -u -v 127.0.0.1 3030 +{{< /code >}} + +### Socket event format + +The agent TCP and UDP sockets use a special event data format designed for backward compatibility with Sensu Core 1.x check results. +Attributes specified in socket events appear in the resulting event data passed to the Sensu backend. + +**Example socket input: Minimum required attributes** + +{{< code json >}} +{ + "name": "check-mysql-status", + "status": 1, + "output": "error!" +} +{{< /code >}} + +**Example socket input: All attributes** + +{{< code json >}} +{ + "name": "check-http", + "status": 1, + "output": "404", + "source": "sensu-docs-site", + "executed": 1550013435, + "duration": 1.903135228, + "handlers": ["slack", "influxdb"] +} +{{< /code >}} + +### Socket event specification + +{{% notice note %}} +**NOTE**: The Sensu agent socket ignores any attributes that are not included in this specification. +{{% /notice %}} + +name | +-------------|------ +description | Check name. +required | true +type | String +example | {{< code json >}}{ + "name": "check-mysql-status" +}{{< /code >}} + +status | +-------------|------ +description | Check execution exit status code. An exit status code of `0` (zero) indicates `OK`, `1` indicates `WARNING`, and `2` indicates `CRITICAL`. Exit status codes other than `0`, `1`, and `2` indicate an `UNKNOWN` or custom status. +required | true +type | Integer +example | {{< code json >}}{ + "status": 0 +}{{< /code >}} + +output | +-------------|------ +description | Output produced by the check `command`. +required | true +type | String +example | {{< code json >}}{ + "output": "CheckHttp OK: 200, 78572 bytes" +}{{< /code >}} + +source | +-------------|------ +description | Name of the Sensu entity associated with the event. Use this attribute to tie the event to a proxy entity. If no matching entity exists, Sensu creates a proxy entity with the name provided by the `source` attribute. +required | false +default | The agent entity that receives the event data. +type | String +example | {{< code json >}}{ + "source": "sensu-docs-site" +}{{< /code >}} + +client | +-------------|------ +description | Name of the Sensu entity associated with the event. Use this attribute to tie the event to a proxy entity. If no matching entity exists, Sensu creates a proxy entity with the name provided by the `client` attribute. {{% notice note %}} +**NOTE**: The `client` attribute is deprecated in favor of the `source` attribute. +{{% /notice %}} +required | false +default | The agent entity that receives the event data. +type | String +example | {{< code json >}}{ + "client": "sensu-docs-site" +}{{< /code >}} + +executed | +-------------|------ +description | Time at which the check was executed. In seconds since the Unix epoch. +required | false +default | The time the event was received by the agent. +type | Integer +example | {{< code json >}}{ + "executed": 1458934742 +}{{< /code >}} + +duration | +-------------|------ +description | Amount of time it took to execute the check. In seconds. +required | false +type | Float +example | {{< code json >}}{ + "duration": 1.903135228 +}{{< /code >}} + +command | +-------------|------ +description | Command executed to produce the event. Use the `command` attribute to add context to the event data. Sensu does not execute the command included in this attribute. +required | false +type | String +example | {{< code json >}}{ + "command": "http-check --url https://sensu.io" +}{{< /code >}} + +interval | +-------------|------ +description | Interval used to produce the event. Use the `interval` attribute to add context to the event data. Sensu does not act on the value provided in this attribute. +required | false +default | `1` +type | Integer +example | {{< code json >}}{ + "interval": 60 +}{{< /code >}} + +handlers | +-------------|------ +description | Array of Sensu handler names to use for handling the event. Each handler name in the array must be a string. +required | false +type | Array +example | {{< code json >}}{ + "handlers": ["slack", "influxdb"] +}{{< /code >}} + +## Registration, endpoint management, and service discovery + +Sensu agents automatically discover and register infrastructure components and the services running on them. +When an agent process stops, the Sensu backend can automatically create and process a deregistration event for the agent entities. + +Read [Automatically register and deregister entities][11] for more information. + +## Agent configuration options + +Agent configuration is customizable. +This section describes each configuration option in more detail, including examples for each [configuration method][70]. + +You can customize agent configuration with the [agent configuration file][69] (Linux and Windows), [command line flag arguments][24] (Linux), or [environment variables][50] (Linux and Windows). + +{{% notice note %}} +**NOTE**: The agent loads configuration upon startup, so you must restart the agent for any configuration updates to take effect. +{{% /notice %}} + +To view available configuration options for the `sensu-agent start` command, run: + +{{< code shell >}} +sensu-agent start --help +{{< /code >}} + +The response will list configuration options as command line flags for `sensu-agent start`: + +{{< code text >}} +start the sensu agent + +Usage: + sensu-agent start [flags] + +Flags: + --agent-managed-entity manage this entity via the agent + --allow-list string path to agent execution allow list configuration file + --annotations stringToString entity annotations map (default []) + --api-host string address to bind the Sensu client HTTP API to (default "127.0.0.1") + --api-port int port the Sensu client HTTP API listens on (default 3031) + --assets-burst-limit int asset fetch burst limit (default 100) + --assets-rate-limit float maximum number of assets fetched per second + --backend-handshake-timeout int number of seconds the agent should wait when negotiating a new WebSocket connection (default 15) + --backend-heartbeat-interval int interval at which the agent should send heartbeats to the backend (default 30) + --backend-heartbeat-timeout int number of seconds the agent should wait for a response to a hearbeat (default 45) + --backend-url strings comma-delimited list of ws/wss URLs of Sensu backend servers. This flag can also be invoked multiple times (default [ws://127.0.0.1:8081]) + --cache-dir string path to store cached data (default "/var/cache/sensu/sensu-agent") + --cert-file string certificate for TLS authentication + -c, --config-file string path to sensu-agent config file (default "/etc/sensu/agent.yml") + --deregister ephemeral agent + --deregistration-handler string deregistration handler that should process the entity deregistration event + --detect-cloud-provider enable cloud provider detection + --disable-api disable the Agent HTTP API + --disable-assets disable check assets on this agent + --disable-sockets disable the Agent TCP and UDP event sockets + --discover-processes indicates whether process discovery should be enabled + --events-burst-limit int /events api burst limit (default 10) + --events-rate-limit float maximum number of events transmitted to the backend through the /events api + -h, --help help for start + --insecure-skip-tls-verify skip TLS verification (not recommended!) + --keepalive-critical-timeout uint32 number of seconds until agent is considered dead by backend to create a critical event + --keepalive-handlers strings comma-delimited list of keepalive handlers for this entity. This flag can also be invoked multiple times + --keepalive-interval int number of seconds to send between keepalive events (default 20) + --keepalive-pipelines strings comma-delimited list of pipeline references for keepalive event + --keepalive-warning-timeout uint32 number of seconds until agent is considered dead by backend to create a warning event (default 120) + --key-file string key for TLS authentication + --labels stringToString entity labels map (default []) + --log-level string logging level [panic, fatal, error, warn, info, debug] (default "info") + --max-session-length maximum amount of time after which the agent will reconnect to one of the configured backends (no maximum by default) + --name string agent name (defaults to hostname) (default "my_hostname") + --namespace string agent namespace (default "default") + --password string agent password (default "P@ssw0rd!") + --redact strings comma-delimited list of fields to redact, overwrites the default fields. This flag can also be invoked multiple times (default [password,passwd,pass,api_key,api_token,access_key,secret_key,private_key,secret]) + --require-fips indicates whether fips support should be required in openssl + --retry-max maximum amount of time to wait before retrying an agent connection to the backend + --retry-min minimum amount of time to wait before retrying an agent connection to the backend + --retry-multiplier value multiplied with the current retry delay to produce a longer retry delay (bounded by --retry-max) + --socket-host string address to bind the Sensu client socket to (default "127.0.0.1") + --socket-port int port the Sensu client socket listens on (default 3030) + --statsd-disable disables the statsd listener and metrics server + --statsd-event-handlers strings comma-delimited list of event handlers for statsd metrics. This flag can also be invoked multiple times + --statsd-flush-interval int number of seconds between statsd flush (default 10) + --statsd-metrics-host string address used for the statsd metrics server (default "127.0.0.1") + --statsd-metrics-port int port used for the statsd metrics server (default 8125) + --strip-networks do not include Network info in agent entity state + --subscriptions strings comma-delimited list of agent subscriptions. This flag can also be invoked multiple times + --trusted-ca-file string TLS CA certificate bundle in PEM format + --user string agent user (default "agent") +{{< /code >}} + +{{% notice note %}} +**NOTE**: Process discovery is disabled in this version of Sensu. +The `discover-processes` configuration option is not available, and new events will not include data in the `processes` attributes. +Instead, the field will be empty: `"processes": null`. +{{% /notice %}} + +### General configuration + + + +| agent-managed-entity | | +-------------|------ +description | Indicates whether the agent's entity solely managed by the agent rather than the backend API. Agent-managed entity definitions will include the label `sensu.io/managed_by: sensu-agent`, and you cannot update these agent-managed entities via the Sensu backend REST API. +required | false +type | Boolean +default | false +environment variable | `SENSU_AGENT_MANAGED_ENTITY` +command line example | {{< code shell >}} +sensu-agent start --agent-managed-entity{{< /code >}} +agent.yml config file example | {{< code shell >}} +agent-managed-entity: true{{< /code >}} + + + +| allow-list | | +------------------|------ +description | Path to yaml or json file that contains the allow list of check or hook commands the agent can execute. Read [Allow list configuration][49] and the [example allow list configuration][48] for information about building a configuration file. +type | String +default | `""` +environment variable | `SENSU_ALLOW_LIST` +command line example | {{< code shell >}} +sensu-agent start --allow-list /etc/sensu/check-allow-list.yaml{{< /code >}} +agent.yml config file example | {{< code shell >}} +allow-list: /etc/sensu/check-allow-list.yaml{{< /code >}} + + + +| annotations| | +-------------|------ +description | Non-identifying metadata to include with event data that you can access with [event filters][9] and [tokens][27]. You can use annotations to add data that is meaningful to people or external tools that interact with Sensu.

    In contrast to labels, you cannot use annotations in [API response filtering][25], [sensuctl response filtering][26], or [web UI view filtering][54].{{% notice note %}} +**NOTE**: For annotations that you define in agent.yml, the keys are automatically modified to use all lower-case letters. For example, if you define the annotation `webhookURL: "https://my-webhook.com"` in agent.yml, it will be listed as `webhookurl: "https://my-webhook.com"` in entity definitions.

    Key cases are **not** modified for annotations you define with the `--annotations` command line flag or the `SENSU_ANNOTATIONS` environment variable. +{{% /notice %}} +required | false +type | Map of key-value pairs. Keys and values can be any valid UTF-8 string. +default | `null` +environment variable | `SENSU_ANNOTATIONS` +command line example | {{< code shell >}} +sensu-agent start --annotations sensu.io/plugins/slack/config/webhook-url=https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX +sensu-agent start --annotations example-key="example value" --annotations example-key2="example value" +{{< /code >}} +agent.yml config file example | {{< code shell >}} +annotations: + sensu.io/plugins/slack/config/webhook-url: "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX" +{{< /code >}} + + + +| assets-burst-limit | | +--------------|------ +description | Maximum amount of burst allowed in a rate interval when fetching dynamic runtime assets. +type | Integer +default | `100` +environment variable | `SENSU_ASSETS_BURST_LIMIT` +command line example | {{< code shell >}} +sensu-agent start --assets-burst-limit 100{{< /code >}} +agent.yml config file example | {{< code shell >}} +assets-burst-limit: 100{{< /code >}} + +| assets-rate-limit | | +--------------|------ +description | Maximum number of dynamic runtime assets to fetch per second. The default value `1.39` is equivalent to approximately 5000 user-to-server requests per hour. +type | Float +default | `1.39` +environment variable | `SENSU_ASSETS_RATE_LIMIT` +command line example | {{< code shell >}} +sensu-agent start --assets-rate-limit 1.39{{< /code >}} +agent.yml config file example | {{< code shell >}} +assets-rate-limit: 1.39{{< /code >}} + + + +| backend-handshake-timeout | | +----------------------------|------ +description | Number of seconds the Sensu agent should wait when negotiating a new WebSocket connection. +type | Integer +default | `15` +environment variable | `SENSU_BACKEND_HANDSHAKE_TIMEOUT` +command line example | {{< code shell >}} +sensu-agent start --backend-handshake-timeout 20{{< /code >}} +agent.yml config file example | {{< code shell >}} +backend-handshake-timeout: 20{{< /code >}} + + + +| backend-heartbeat-interval | | +-----------------------------|------ +description | Interval at which the agent should send heartbeats to the Sensu backend. In seconds. +type | Integer +default | `30` +environment variable | `SENSU_BACKEND_HEARTBEAT_INTERVAL` +command line example | {{< code shell >}} +sensu-agent start --backend-heartbeat-interval 45{{< /code >}} +agent.yml config file example | {{< code shell >}} +backend-heartbeat-interval: 45{{< /code >}} + + + +| backend-heartbeat-timeout | | +----------------------------|------ +description | Number of seconds the agent should wait for a response to a hearbeat from the Sensu backend. +type | Integer +default | `45` +environment variable | `SENSU_BACKEND_HEARTBEAT_TIMEOUT` +command line example | {{< code shell >}} +sensu-agent start --backend-heartbeat-timeout 60{{< /code >}} +agent.yml config file example | {{< code shell >}} +backend-heartbeat-timeout: 60{{< /code >}} + +| backend-url | | +--------------|------ +description | ws or wss URL of the Sensu backend server. To specify multiple backends with `sensu-agent start`, use this flag multiple times. {{% notice note %}} +**NOTE**: If you do not specify a port for your backend-url values, the agent will automatically append the default backend port (8081). +{{% /notice %}} +type | List +default | `ws://127.0.0.1:8081`(Debian and RHEL families)

    `$SENSU_HOSTNAME:8080` (Docker){{% notice note %}} +**NOTE**: Docker-only Sensu binds to the hostnames of containers, represented here as `SENSU_HOSTNAME` in Docker default values. +{{% /notice %}} +environment variable | `SENSU_BACKEND_URL` +command line example | {{< language-toggle >}} +{{< code shell "ws" >}} +sensu-agent start --backend-url ws://127.0.0.1:8081 +sensu-agent start --backend-url ws://127.0.0.1:8081 --backend-url ws://127.0.0.1:8082 +{{< /code >}} +{{< code shell "wss" >}} +sensu-agent start --backend-url wss://127.0.0.1:8081 +sensu-agent start --backend-url wss://127.0.0.1:8081 --backend-url wss://127.0.0.1:8082 +{{< /code >}} +{{< /language-toggle >}} +agent.yml config file example | {{< language-toggle >}} +{{< code shell "ws" >}} +backend-url: + - "ws://127.0.0.1:8081" + - "ws://127.0.0.1:8082" +{{< /code >}} +{{< code shell "wss" >}} +backend-url: + - "wss://127.0.0.1:8081" + - "wss://127.0.0.1:8082" +{{< /code >}} +{{< /language-toggle >}} + + + +| cache-dir | | +--------------|------ +description | Path to store cached data. +type | String +default |
    • Linux: `/var/cache/sensu/sensu-agent`
    • Windows: `C:\ProgramData\sensu\cache\sensu-agent`
    +environment variable | `SENSU_CACHE_DIR` +command line example | {{< code shell >}} +sensu-agent start --cache-dir /cache/sensu-agent{{< /code >}} +agent.yml config file example | {{< code shell >}} +cache-dir: "/cache/sensu-agent"{{< /code >}} + + + +| config-file | | +--------------|------ +description | Path to Sensu agent configuration file. +type | String +default |
    • Linux: `/etc/sensu/agent.yml`
    • FreeBSD: `/usr/local/etc/sensu/agent.yml`
    • Windows: `C:\ProgramData\sensu\config\agent.yml`
    +environment variable | `SENSU_CONFIG_FILE` +command line example | {{< code shell >}} +sensu-agent start --config-file /sensu/agent.yml +sensu-agent start -c /sensu/agent.yml +{{< /code >}} + + + +| disable-assets | | +--------------|------ +description | When set to `true`, disables [dynamic runtime assets][29] for the agent. If an agent attempts to execute a check that requires a dynamic runtime asset, the agent will respond with a status of `3` and a message that indicates the agent could not execute the check because assets are disabled. +type | Boolean +default | false +environment variable | `SENSU_DISABLE_ASSETS` +command line example | {{< code shell >}} +sensu-agent start --disable-assets{{< /code >}} +agent.yml config file example | {{< code shell >}} +disable-assets: true{{< /code >}} + + + +| discover-processes | | +--------------|------ +description | When set to `true`, the agent populates the `processes` field in `entity.system` and updates every 20 seconds.{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access the `discover-processes` configuration option in the packaged Sensu Go distribution. For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}}{{% notice note %}} +**NOTE**: Process discovery is disabled in this version of Sensu. The discover-processes flag is not available, and new events will not include data in the `processes` attributes. Instead, the field will be empty: `"processes": null`. +{{% /notice %}} +type | Boolean +default | false +environment variable | `SENSU_DISCOVER_PROCESSES` +command line example | {{< code shell >}} +sensu-agent start --discover-processes{{< /code >}} +agent.yml config file example | {{< code shell >}} +discover-processes: true{{< /code >}} + +| labels | | +-------------|------ +description | Custom attributes to include with event data that you can use for response and web UI view filtering.

    If you include labels in your event data, you can filter [API responses][25], [sensuctl responses][26], and [web UI views][54] based on them. In other words, labels allow you to create meaningful groupings for your data.

    Limit labels to metadata you need to use for response filtering. For complex, non-identifying metadata that you will *not* need to use in response filtering, use annotations rather than labels.{{% notice note %}} +**NOTE**: For labels that you define in agent.yml, the keys are automatically modified to use all lower-case letters. For example, if you define the label `proxyType: "website"` in agent.yml, it will be listed as `proxytype: "website"` in entity definitions.

    Key cases are **not** modified for labels you define with the `--labels` command line flag or the `SENSU_LABELS` environment variable. +{{% /notice %}} +required | false +type | Map of key-value pairs. Keys can contain only letters, numbers, and underscores and must start with a letter. Values can be any valid UTF-8 string. +default | `null` +environment variable | `SENSU_LABELS` +command line example | {{< code shell >}} +sensu-agent start --labels proxy_type=website +sensu-agent start --labels example_key1="example value" example_key2="example value" +{{< /code >}} +agent.yml config file example | {{< code shell >}} +labels: + proxy_type: website +{{< /code >}} + + + +| log-level | | +--------------|------ +description | Logging level: `panic`, `fatal`, `error`, `warn`, `info`, or `debug`. +type | String +default | `warn` +environment variable | `SENSU_LOG_LEVEL` +command line example | {{< code shell >}} +sensu-agent start --log-level debug{{< /code >}} +agent.yml config file example | {{< code shell >}} +log-level: debug{{< /code >}} + + + +| max-session-length | | +--------------|------ +description | Maximum duration for any one agent connection. In milliseconds (`ms`), seconds (`s`), minutes (`m`), or hours (`h`). Use max-session-length to prevent agent connection distribution from becoming skewed over time.

    The max-session-length algorithm includes random jitter so that agents will not disconnect and reconnect all at once. Based on the random jitter calculation, at some time before a connection reaches the specified maximum duration, Sensu will force the agent to disconnect and reconnect to an available configured backend. +type | String +default | Defaults to no maximum. +environment variable | `SENSU_MAX_SESSION_LENGTH` +command line example | {{< code shell >}} +sensu-agent start --max-session-length 15m{{< /code >}} +agent.yml config file example | {{< code shell >}} +max-session-length: 15m{{< /code >}} + + + +| name | | +--------------|------ +description | Entity name assigned to the agent entity. +type | String +default | Defaults to hostname (for example, `sensu-centos`). +environment variable | `SENSU_NAME` +command line example | {{< code shell >}} +sensu-agent start --name agent-01{{< /code >}} +agent.yml config file example | {{< code shell >}} +name: "agent-01"{{< /code >}} + + + +| retry-max | | +--------------|------ +description | Maximum amount of time to wait before retrying an agent connection to the backend. In milliseconds (`ms`), seconds (`s`), minutes (`m`), or hours (`h`). +type | String +default | `120s` +environment variable | `SENSU_RETRY_MAX` +command line example | {{< code shell >}} +sensu-agent start --retry-max 120s{{< /code >}} +agent.yml config file example | {{< code shell >}} +retry-max: 120s{{< /code >}} + + + +| retry-min | | +--------------|------ +description | Minimum amount of time to wait before retrying an agent connection to the backend. Multiplied with the [retry-multiplier][62] value at each retry. In milliseconds (`ms`), seconds (`s`), minutes (`m`), or hours (`h`). +type | String +default | `1s` +environment variable | `SENSU_RETRY_MIN` +command line example | {{< code shell >}} +sensu-agent start --retry-min 1s{{< /code >}} +agent.yml config file example | {{< code shell >}} +retry-min: 1s{{< /code >}} + + + +| retry-multiplier | | +--------------|------ +description | Value to multiply with the current [retry-min][61] delay to produce longer delays at each retry for exponential backoff.{{% notice note %}} +**NOTE**: The maximum retry delay cannot not exceed the [retry-max](#retry-max) value. +{{% /notice %}} +type | Float +default | `2.0` +environment variable | `SENSU_RETRY_MULTIPLIER` +command line example | {{< code shell >}} +sensu-agent start --retry-multiplier 2.0{{< /code >}} +agent.yml config file example | {{< code shell >}} +retry-multiplier: 2.0{{< /code >}} + + + +| subscriptions | | +----------------|------ +description | When set to `true`, prevents network information from being collected by the Sensu agent. +type | Boolean +environment variable | `SENSU_STRIP_NETWORKS` +command line example | {{< code shell >}} +sensu-agent start --strip-networks +{{< /code >}} +agent.yml config file example | {{< code shell >}} +strip-networks: true +{{< /code >}} + + + +| subscriptions | | +----------------|------ +description | Array of agent subscriptions that determine which monitoring checks the agent will execute. The subscriptions array items must be strings. +type | List +environment variable | `SENSU_SUBSCRIPTIONS` +command line example | {{< code shell >}} +sensu-agent start --subscriptions disk-checks,process-checks +sensu-agent start --subscriptions disk-checks --subscriptions process-checks +{{< /code >}} +agent.yml config file example | {{< code shell >}} +subscriptions: + - disk-checks + - process-checks +{{< /code >}} + +### API configuration + +| api-host | | +--------------|------ +description | Bind address for the Sensu agent HTTP API. +type | String +default | `127.0.0.1` +environment variable | `SENSU_API_HOST` +command line example | {{< code shell >}} +sensu-agent start --api-host 127.0.0.1{{< /code >}} +agent.yml config file example | {{< code shell >}} +api-host: "127.0.0.1"{{< /code >}} + +| api-port | | +--------------|------ +description | Listening port for the Sensu agent HTTP API. +type | Integer +default | `3031` +environment variable | `SENSU_API_PORT` +command line example | {{< code shell >}} +sensu-agent start --api-port 3031{{< /code >}} +agent.yml config file example | {{< code shell >}} +api-port: 3031{{< /code >}} + +| disable-api | | +--------------|------ +description | `true` to disable the agent HTTP API. Otherwise, `false`. +type | Boolean +default | `false` +environment variable | `SENSU_DISABLE_API` +command line example | {{< code shell >}} +sensu-agent start --disable-api{{< /code >}} +agent.yml config file example | {{< code shell >}} +disable-api: true{{< /code >}} + +| events-burst-limit | | +--------------|------ +description | Maximum amount of burst allowed in a rate interval for the [agent events API][51]. +type | Integer +default | `10` +environment variable | `SENSU_EVENTS_BURST_LIMIT` +command line example | {{< code shell >}} +sensu-agent start --events-burst-limit 20{{< /code >}} +agent.yml config file example | {{< code shell >}} +events-burst-limit: 20{{< /code >}} + +| events-rate-limit | | +--------------|------ +description | Maximum number of events per second that can be transmitted to the backend with the [agent events API][51]. +type | Float +default | `10.0` +environment variable | `SENSU_EVENTS_RATE_LIMIT` +command line example | {{< code shell >}} +sensu-agent start --events-rate-limit 20.0{{< /code >}} +agent.yml config file example | {{< code shell >}} +events-rate-limit: 20.0{{< /code >}} + +### Ephemeral agent configuration + +| deregister | | +--------------|------ +description | `true` if a deregistration event should be created upon Sensu agent process stop. Otherwise, `false`.
    {{% notice note %}} +**NOTE**: To receive alerts for failing [keepalives](#keepalive-monitoring), set to `false`. +{{% /notice %}} +type | Boolean +default | `false` +environment variable | `SENSU_DEREGISTER` +command line example | {{< code shell >}} +sensu-agent start --deregister{{< /code >}} +agent.yml config file example | {{< code shell >}} +deregister: true{{< /code >}} + + + +| deregistration-handler | | +-------------------------|------ +description | Name of the event handler to use when processing the agent's deregistration events. This configuration option overrides any handlers applied by the [`deregistration-handler`][37] backend configuration option. +type | String +environment variable | `SENSU_DEREGISTRATION_HANDLER` +command line example | {{< code shell >}} +sensu-agent start --deregistration-handler deregister{{< /code >}} +agent.yml config file example | {{< code shell >}} +deregistration-handler: deregister{{< /code >}} + + + +| detect-cloud-provider | | +-------------------------|------ +description | `true` to enable cloud provider detection mechanisms. Otherwise, `false`. When this option is enabled, the agent will attempt to read files, resolve hostnames, and make HTTP requests to determine what cloud environment it is running in. +type | Boolean +default | `false` +environment variable | `SENSU_DETECT_CLOUD_PROVIDER` +command line example | {{< code shell >}} +sensu-agent start --detect-cloud-provider false{{< /code >}} +agent.yml config file example | {{< code shell >}} +detect-cloud-provider: false{{< /code >}} + +### Keepalive configuration + +| keepalive-critical-timeout | | +--------------------|------ +description | Number of seconds after a missing keepalive event until the agent is considered unresponsive by the Sensu backend to create a critical event. Set to disabled (`0`) by default. If the value is not `0`, it must be greater than or equal to `5`.
    {{% notice note %}}**NOTE**: The agent maps the `keepalive-critical-timeout` value to the [`event.check.ttl` attribute](../../observe-events/events/#check-scope) when keepalive events are generated for the Sensu backend to process. The `event.check.ttl` attribute is useful for [creating time-based event filters](../../observe-filter/filters#filter-to-reduce-alert-fatigue-for-keepalive-events) to reduce alert fatigue for agent keepalive events. +{{% /notice %}} +type | Integer +default | `0` +environment variable | `SENSU_KEEPALIVE_CRITICAL_TIMEOUT` +command line example | {{< code shell >}} +sensu-agent start --keepalive-critical-timeout 300{{< /code >}} +agent.yml config file example | {{< code shell >}} +keepalive-critical-timeout: 300{{< /code >}} + + + +| keepalive-handlers | | +--------------------|------ +description | [Keepalive event handlers][52] to use for the entity, specified in a comma-delimited list. You can specify any configured handler and invoke the `keepalive-handlers` configuration option multiple times. If keepalive handlers are not specified, the Sensu backend will use the default `keepalive` handler and create an event in sensuctl and the Sensu web UI. +type | List +default | `keepalive` +environment variable | `SENSU_KEEPALIVE_HANDLERS` +command line example | {{< code shell >}} +sensu-agent start --keepalive-handlers slack,email{{< /code >}} +agent.yml config file example | {{< code shell >}} +keepalive-handlers: +- slack +- email +{{< /code >}} + +| keepalive-interval | | +---------------------|------ +description | Number of seconds between keepalive events. +type | Integer +default | `20` +environment variable | `SENSU_KEEPALIVE_INTERNAL` +command line example | {{< code shell >}} +sensu-agent start --keepalive-interval 30{{< /code >}} +agent.yml config file example | {{< code shell >}} +keepalive-interval: 30{{< /code >}} + + + +| keepalive-pipelines | | +--------------------|------ +description | [Pipelines][63] to use for processing keepalive events, specified in a comma-delimited list. If keepalive pipelines are not specified, the Sensu backend will use the default `keepalive` handler and create an event in sensuctl and the Sensu web UI.

    To specify pipelines for the `keepalive-pipelines` configuration option, use the [fully qualified name][65] for pipeline resources (`core/v2.Pipeline`) plus the pipeline name. +type | List +default | `keepalive` +environment variable | `SENSU_KEEPALIVE_PIPELINES` +command line example | {{< code shell >}} +sensu-agent start --keepalive-pipelines core/v2.Pipeline.slack,core/v2.Pipeline.store-keepalives{{< /code >}} +agent.yml config file example | {{< code shell >}} +keepalive-pipelines: +- core/v2.Pipeline.slack +- core/v2.Pipeline.store-keepalives +{{< /code >}} + + + +| keepalive-warning-timeout | | +--------------------|------ +description | Number of seconds after a missing keepalive event until the agent is considered unresponsive by the Sensu backend to create a warning event. Value must be lower than the `keepalive-critical-timeout` value. Minimum value is `5`.
    {{% notice note %}}**NOTE**: The agent maps the `keepalive-warning-timeout` value to the [`event.check.timeout` attribute](../../observe-events/events/#check-scope) when keepalive events are generated for the Sensu backend to process. The `event.check.timeout` attribute is useful for [creating time-based event filters](../../observe-filter/filters#filter-to-reduce-alert-fatigue-for-keepalive-events) to reduce alert fatigue for agent keepalive events. +{{% /notice %}} +type | Integer +default | `120` +environment variable | `SENSU_KEEPALIVE_WARNING_TIMEOUT` +command line example | {{< code shell >}} +sensu-agent start --keepalive-warning-timeout 300{{< /code >}} +agent.yml config file example | {{< code shell >}} +keepalive-warning-timeout: 300{{< /code >}} + +### Security configuration + +| cert-file | | +-------------|------ +description | Path to the agent certificate file used in mTLS authentication. Sensu supports certificate bundles (or chains) as long as the agent (or leaf) certificate is the *first* certificate in the bundle. +type | String +default | `""` +environment variable | `SENSU_CERT_FILE` +command line example | {{< code shell >}} +sensu-agent start --cert-file /path/to/tls/agent.pem{{< /code >}} +agent.yml config file example | {{< code shell >}} +cert-file: "/path/to/tls/agent.pem"{{< /code >}} + +| insecure-skip-tls-verify | | +---------------------------|------ +description | Skip SSL verification. {{% notice warning %}} +**WARNING**: This configuration option is intended for use in development systems only. Do not use this configuration option in production. +{{% /notice %}} +type | Boolean +default | `false` +environment variable | `SENSU_INSECURE_SKIP_TLS_VERIFY` +command line example | {{< code shell >}} +sensu-agent start --insecure-skip-tls-verify{{< /code >}} +agent.yml config file example | {{< code shell >}} +insecure-skip-tls-verify: true{{< /code >}} + +| key-file | | +-------------|------ +description | Path to the agent key file used in mTLS authentication. +type | String +default | `""` +environment variable | `SENSU_KEY_FILE` +command line example | {{< code shell >}} +sensu-agent start --key-file /path/to/tls/agent-key.pem{{< /code >}} +agent.yml config file example | {{< code shell >}} +key-file: "/path/to/tls/agent-key.pem"{{< /code >}} + +| namespace | | +---------------|------ +description | Agent namespace. {{% notice note %}} +**NOTE**: Agents are represented in the backend as a class of entity. +Entities can only belong to a [single namespace](../../../operations/control-access/rbac/#namespaced-resource-types). +{{% /notice %}} +type | String +default | `default` +environment variable | `SENSU_NAMESPACE` +command line example | {{< code shell >}} +sensu-agent start --namespace ops{{< /code >}} +agent.yml config file example | {{< code shell >}} +namespace: ops{{< /code >}} + + + +| password | | +--------------|------ +description | [Sensu RBAC password][39] used by the agent. +type | String +default | `P@ssw0rd!` +environment variable | `SENSU_PASSWORD` +command line example | {{< code shell >}} +sensu-agent start --password secure-password{{< /code >}} +agent.yml config file example | {{< code shell >}} +password: secure-password{{< /code >}} + +| redact | | +--------------|------ +description | List of fields to redact when displaying the entity. {{% notice note %}} +**NOTE**: Redacted secrets are sent via the WebSocket connection and stored in etcd. +They are not logged or displayed via the Sensu API. +{{% /notice %}} +type | List +default | By default, Sensu redacts the following fields: `password`, `passwd`, `pass`, `api_key`, `api_token`, `access_key`, `secret_key`, `private_key`, `secret`. +environment variable | `SENSU_REDACT` +command line example | {{< code shell >}} +sensu-agent start --redact secret,ec2_access_key{{< /code >}} +agent.yml config file example | {{< code shell >}} +redact: + - secret + - ec2_access_key +{{< /code >}} + + + +| require-fips | | +------------------|------ +description | Require Federal Information Processing Standard (FIPS) support in OpenSSL. Logs an error at Sensu agent startup if `true` but OpenSSL is not running in FIPS mode. {{% notice note %}} +**NOTE**: The `require-fips` configuration option is only available within the Linux amd64 OpenSSL-linked binary. +[Contact Sensu](https://sensu.io/contact) to request the builds for OpenSSL with FIPS support. +{{% /notice %}} +type | Boolean +default | false +environment variable | `SENSU_REQUIRE_FIPS` +command line example | {{< code shell >}} +sensu-agent start --require-fips{{< /code >}} +agent.yml config file example | {{< code shell >}} +require-fips: true{{< /code >}} + +| trusted-ca-file | | +------------------|------ +description | SSL/TLS certificate authority. +type | String +default | `""` +environment variable | `SENSU_TRUSTED_CA_FILE` +command line example | {{< code shell >}} +sensu-agent start --trusted-ca-file /path/to/tls/ca.pem{{< /code >}} +agent.yml config file example | {{< code shell >}} +trusted-ca-file: "/path/to/tls/ca.pem"{{< /code >}} + + + +| user | | +--------------|------ +description | [Sensu RBAC username][39] used by the agent. Agents require get, list, create, update, and delete permissions for events across all namespaces. +type | String +default | `agent` +environment variable | `SENSU_USER` +command line example | {{< code shell >}} +sensu-agent start --user agent-01{{< /code >}} +agent.yml config file example | {{< code shell >}} +user: "agent-01"{{< /code >}} + +### Socket configuration + +| disable-sockets | | +------------------|------ +description | `true` to disable the agent TCP and UDP event sockets. Othewise, `false`. +type | Boolean +default | `false` +environment variable | `SENSU_DISABLE_SOCKETS` +command line example | {{< code shell >}} +sensu-agent start --disable-sockets{{< /code >}} +agent.yml config file example | {{< code shell >}} +disable-sockets: true{{< /code >}} + +| socket-host | | +--------------|------ +description | Address to bind the Sensu agent socket to. +type | String +default | `127.0.0.1` +environment variable | `SENSU_SOCKET_HOST` +command line example | {{< code shell >}} +sensu-agent start --socket-host 127.0.0.1{{< /code >}} +agent.yml config file example | {{< code shell >}} +socket-host: "127.0.0.1"{{< /code >}} + +| socket-port | | +--------------|------ +description | Port the Sensu agent socket listens on. +type | Integer +default | `3030` +environment variable | `SENSU_SOCKET_PORT` +command line example | {{< code shell >}} +sensu-agent start --socket-port 3030{{< /code >}} +agent.yml config file example | {{< code shell >}} +socket-port: 3030{{< /code >}} + +### StatsD configuration + +| statsd-disable | | +-----------------|------ +description | `true` to disable the [StatsD][21] listener and metrics server. Otherwise, `false`. +type | Boolean +default | `false` +environment variable | `SENSU_STATSD_DISABLE` +command line example | {{< code shell >}} +sensu-agent start --statsd-disable{{< /code >}} +agent.yml config file example | {{< code shell >}} +statsd-disable: true{{< /code >}} + +| statsd-event-handlers | | +------------------------|------ +description | List of event handlers for StatsD metrics. +type | List +environment variable | `SENSU_STATSD_EVENT_HANDLERS` +command line example | {{< code shell >}} +sensu-agent start --statsd-event-handlers influxdb,opentsdb +sensu-agent start --statsd-event-handlers influxdb --statsd-event-handlers opentsdb +{{< /code >}} +agent.yml config file example | {{< code shell >}} +statsd-event-handlers: + - influxdb + - opentsdb +{{< /code >}} + +| statsd-flush-interval | | +-------------------------|------ +description | Number of seconds between [StatsD flushes][23]. +type | Integer +default | `10` +environment variable | `SENSU_STATSD_FLUSH_INTERVAL` +command line example | {{< code shell >}} +sensu-agent start --statsd-flush-interval 30{{< /code >}} +agent.yml config file example | {{< code shell >}} +statsd-flush-interval: 30{{< /code >}} + +| statsd-metrics-host | | +----------------------|------ +description | Address used for the StatsD metrics server. +type | String +default | `127.0.0.1` +environment variable | `SENSU_STATSD_METRICS_HOST` +command line example | {{< code shell >}} +sensu-agent start --statsd-metrics-host 127.0.0.1{{< /code >}} +agent.yml config file example | {{< code shell >}} +statsd-metrics-host: "127.0.0.1"{{< /code >}} + +| statsd-metrics-port | | +----------------------|------ +description | Port used for the StatsD metrics server. +type | Integer +default | `8125` +environment variable | `SENSU_STATSD_METRICS_PORT` +command line example | {{< code shell >}} +sensu-agent start --statsd-metrics-port 8125{{< /code >}} +agent.yml config file example | {{< code shell >}} +statsd-metrics-port: 8125{{< /code >}} + +### Allow list configuration + +The allow list includes check and hook commands the agent can execute. +Use the [`allow-list` configuration option][56] to specify the path to the yaml or json file that contains your allow list. + +Use these commands to build your allow list configuration file. + +| args | | +----------------------|------ +description | Arguments for the `exec` command. +required | true +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +args: +- foo +{{< /code >}} +{{< code json >}} +{ + "args": ["foo"] +} +{{< /code >}} +{{< /language-toggle >}} + +| enable_env | | +----------------------|------ +description | `true` to enable environment variables. Otherwise, `false`. +required | false +type | Boolean +example | {{< language-toggle >}} +{{< code yml >}} +enable_env: true +{{< /code >}} +{{< code json >}} +{ + "enable_env": true +} +{{< /code >}} +{{< /language-toggle >}} + +| exec | | +----------------------|------ +description | Command to allow the Sensu agent to run as a check or a hook. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +exec: "/usr/local/bin/check_memory.sh" +{{< /code >}} +{{< code json >}} +{ + "exec": "/usr/local/bin/check_memory.sh" +} +{{< /code >}} +{{< /language-toggle >}} + +| sha512 | | +----------------------|------ +description | Checksum of the check or hook executable. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +sha512: 4f926bf4328... +{{< /code >}} +{{< code json >}} +{ + "sha512": "4f926bf4328..." +} +{{< /code >}} +{{< /language-toggle >}} + +#### Example allow list configuration + +{{< language-toggle >}} + +{{< code yml >}} +- exec: /usr/local/bin/check_memory.sh + args: + - "" + sha512: 736ac120323772543fd3a08ee54afdd54d214e58c280707b63ce652424313ef9084ca5b247d226aa09be8f831034ff4991bfb95553291c8b3dc32cad034b4706 + enable_env: true + foo: bar +- exec: /usr/local/bin/show_process_table.sh + args: + - "" + sha512: 28d61f303136b16d20742268a896bde194cc99342e02cdffc1c2186f81c5adc53f8550635156bebeed7d87a0c19a7d4b7a690f1a337cc4737e240b62b827f78a +- exec: echo-asset.sh + args: + - "foo" + sha512: cce3d16e5881ba829f271df778f9014f7c3659917f7acfd7a60a91bfcabb472eea72f9781194d310388ba046c21790364ad0308a5a897cde50022195ba90924b +{{< /code >}} + +{{< code json >}} +[ + { + "exec": "/usr/local/bin/check_memory.sh", + "args": [ + "" + ], + "sha512": "736ac120323772543fd3a08ee54afdd54d214e58c280707b63ce652424313ef9084ca5b247d226aa09be8f831034ff4991bfb95553291c8b3dc32cad034b4706", + "enable_env": true, + "foo": "bar" + }, + { + "exec": "/usr/local/bin/show_process_table.sh", + "args": [ + "" + ], + "sha512": "28d61f303136b16d20742268a896bde194cc99342e02cdffc1c2186f81c5adc53f8550635156bebeed7d87a0c19a7d4b7a690f1a337cc4737e240b62b827f78a" + }, + { + "exec": "echo-asset.sh", + "args": [ + "foo" + ], + "sha512": "cce3d16e5881ba829f271df778f9014f7c3659917f7acfd7a60a91bfcabb472eea72f9781194d310388ba046c21790364ad0308a5a897cde50022195ba90924b" + } +] +{{< /code >}} + +{{< /language-toggle >}} + +## Agent configuration methods + +### Agent configuration file + +For Linux and Windows agents, you can customize the agent configuration in a `.yml` configuration file. + +The default agent configuration file path for Linux is `/etc/sensu/agent.yml`. +The default agent configuration file path for Windows is `C:\ProgramData\sensu\config\agent.yml.example`. + +To use the `agent.yml` file to configure the agent, list the desired configuration attributes and values. +Review the [example Sensu agent configuration file][5] for a complete example. + +{{% notice note %}} +**NOTE**: The agent loads configuration upon startup. +If you make changes in the `agent.yml` configuration file after startup, you must restart the agent for the changes to take effect. +{{% /notice %}} + +Configuration via command line flags or environment variables overrides any configuration specified in the agent configuration file. +Read [Create overrides][68] to learn more. + +### Command line flags + +For Linux agents, you can customize the agent configuration with `sensu-agent start` command line flags. + +To use command line flags, specify the desired configuration options and values along with the `sensu-agent start` command. +For example: + +{{< code shell >}} +sensu-agent start --name webserver_05 --keepalive-warning-timeout 60 --keepalive-critical-timeout 120 +{{< /code >}} + +Configuration via command line flags overrides attributes specified in a configuration file or with environment variables. +Read [Create overrides][68] to learn more. + +### Environment variables + +Instead of using the agent configuration file or command line flags, you can use environment variables to configure your Sensu agent. +Each agent configuration option has an associated environment variable. +You can also create your own environment variables, as long as you name them correctly and save them in the correct place. +Here's how. + +1. Create the files from which the `sensu-agent` service configured by our supported packages will read environment variables: + + {{< language-toggle >}} + +{{< code shell "Debian family" >}} +sudo touch /etc/default/sensu-agent +{{< /code >}} + +{{< code shell "RHEL family" >}} +sudo touch /etc/sysconfig/sensu-agent +{{< /code >}} + + {{< /language-toggle >}} + +2. Make sure the environment variable is named correctly. +All environment variables that control Sensu agent configuration begin with `SENSU_`. + + To rename a configuration option you wish to specify as an environment variable, prepend `SENSU_`, convert dashes to underscores, and capitalize all letters. + For example, the environment variable for the flag `api-host` is `SENSU_API_HOST`. + + For a custom environment variable, you do not have to prepend `SENSU`. + For example, `TEST_VAR_1` is a valid custom environment variable name. + +3. Add the environment variable to the environment file. + + In this example, the `api-host` flag is configured as an environment variable and set to `"0.0.0.0"`: + + {{< language-toggle >}} + +{{< code shell "Debian family" >}} +echo 'SENSU_API_HOST="0.0.0.0"' | sudo tee -a /etc/default/sensu-agent +{{< /code >}} + +{{< code shell "RHEL family" >}} +echo 'SENSU_API_HOST="0.0.0.0"' | sudo tee -a /etc/sysconfig/sensu-agent +{{< /code >}} + + {{< /language-toggle >}} + +4. Restart the sensu-agent service so these settings can take effect: + + {{< language-toggle >}} + +{{< code shell "Debian family" >}} +sudo systemctl restart sensu-agent +{{< /code >}} + +{{< code shell "RHEL family" >}} +sudo systemctl restart sensu-agent +{{< /code >}} + + {{< /language-toggle >}} + +{{% notice note %}} +**NOTE**: Sensu includes an environment variable for each agent configuration option. +They are listed in the [configuration description tables](#general-configuration). +{{% /notice %}} + +Environment variables on the Windows agent are located in the Windows Registry. Here's how to add environment variables to the agent. + +1. Open up the `Run` dialog: + +{{< code shell >}} +windows + r +{{< /code >}} + +2. Open the registry editor by typing the following in the `Run` dialog: + +{{< code shell >}} +regedit +{{< /code >}} + +3. Navigate to the following registry path: `Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Environment` + +4. Click Edit --> New --> String Value + +5. Edit the new string entry and change the "Value name" to be `SENSU_API_HOST` and the "Value data" to be `0.0.0.0` + +6. Log out of any sessions on your Windows device, or optionally reboot to have the environment variable loaded. + +### Format for label and annotation environment variables + +To use labels and annotations as environment variables in your check and plugin configurations, you must use a specific format when you create the environment variables. + +For example, to create the labels `"region": "us-east-1"` and `"type": "website"` as an environment variable: + +{{< language-toggle >}} + +{{< code shell "Debian family" >}} +echo 'SENSU_LABELS='{"region": "us-east-1", "type": "website"}'' | sudo tee -a /etc/default/sensu-agent +{{< /code >}} + +{{< code shell "RHEL family" >}} +echo 'SENSU_LABELS='{"region": "us-east-1", "type": "website"}'' | sudo tee -a /etc/sysconfig/sensu-agent +{{< /code >}} + +{{< /language-toggle >}} + +To create the annotations `"maintainer": "Team A"` and `"webhook-url": "https://hooks.slack.com/services/T0000/B00000/XXXXX"` as an environment variable: + +{{< language-toggle >}} + +{{< code shell "Debian family" >}} +echo 'SENSU_ANNOTATIONS='{"maintainer": "Team A", "webhook-url": "https://hooks.slack.com/services/T0000/B00000/XXXXX"}'' | sudo tee -a /etc/default/sensu-agent +{{< /code >}} + +{{< code shell "RHEL family" >}} +echo 'SENSU_ANNOTATIONS='{"maintainer": "Team A", "webhook-url": "https://hooks.slack.com/services/T0000/B00000/XXXXX"}'' | sudo tee -a /etc/sysconfig/sensu-agent +{{< /code >}} + +{{< /language-toggle >}} + +### Use environment variables with the Sensu agent + +Any environment variables you create in `/etc/default/sensu-agent` (Debian family) or `/etc/sysconfig/sensu-agent` (RHEL family) will be available to check and hook commands executed by the Sensu agent. +This includes your checks and plugins. + +For example, if you create a custom environment variable `TEST_VARIABLE` in your sensu-agent file, it will be available to use in your check and hook configurations as `$TEST_VARIABLE`. + +The following check example demonstrates how to use a `TEST_GITHUB_TOKEN` environment variable (set to the token value in the sensu-agent file) in the check command to run a script that pings the GitHub API: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: ping-github-api +spec: + command: ping-github-api.sh $TEST_GITHUB_TOKEN + handlers: + - slack + interval: 10 + publish: true + subscriptions: + - system +{{< /code >}} + +{{< code json >}} +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "ping-github-api" + }, + "spec": { + "command": "ping-github-api.sh $TEST_GITHUB_TOKEN", + "handlers": [ + "slack" + ], + "interval": 10, + "publish": true, + "subscriptions": [ + "system" + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +### Use environment variables to specify an HTTP proxy for agent use + +If an HTTP proxy is required to access the internet in your compute environment, you may need to configure the Sensu agent to successfully download dynamic runtime assets or execute commands that depend on internet access. + +For Sensu agents that require a proxy server, define `HTTP_PROXY` and `HTTPS_PROXY` environment variables in your sensu-agent file. + +{{< code shell >}} +HTTP_PROXY="http://YOUR_PROXY_SERVER:PORT" +HTTPS_PROXY="http://YOUR_PROXY_SERVER:PORT" +{{< /code >}} + +You can use the same proxy server URL for `HTTP_PROXY` and `HTTPS_PROXY`. +The proxy server URL you specify for `HTTPS_PROXY` does not need to use `https://`. + +After you add the `HTTP_PROXY` and `HTTPS_PROXY` environment variables and restart sensu-agent, they will be available to check and hook commands executed by the Sensu agent. +You can then use `HTTP_PROXY` and `HTTPS_PROXY` to add dynamic runtime assets, run checks, and complete other tasks that typically require an internet connection for your unconnected entities. + +{{% notice note %}} +**NOTE**: If you define the `HTTP_PROXY` and `HTTPS_PROXY` environment variables, the agent WebSocket connection will also use the proxy URL you specify. +{{% /notice %}} + +## Create configuration overrides + +Sensu has default settings and limits for certain configuration attributes, like the default log level. +Depending on your environment and preferences, you may want to create overrides for these Sensu-specific defaults and limits. + +You can create configuration overrides in several ways: + +- Command line configuration flag arguments for `sensu-agent start`. +- Environment variables in `/etc/default/sensu-agent` (Debian family) or `/etc/sysconfig/sensu-agent` (RHEL family). +- Configuration settings in the agent.yml config file. + +{{% notice note %}} +**NOTE**: We do not recommend editing the systemd unit file to create overrides. +Future package upgrades can overwrite changes in the systemd unit file. +{{% /notice %}} + +Sensu applies the following precedence to override settings: + +1. Arguments passed to the Sensu agent via command line configuration flags. +2. Environment variables in `/etc/default/sensu-agent` (Debian family) or `/etc/sysconfig/sensu-agent` (RHEL family). +3. Configuration in the agent.yml config file. + +For example, if you create overrides using all three methods, the command line configuration flag values will take precedence over the values you specify in `/etc/default/sensu-agent` or `/etc/sysconfig/sensu-agent` or the agent.yml config file. + +### Example override: Log level + +The default [log level][60] for the Sensu agent is `warn`. + +To override the default and automatically apply a different log level for the agent, add the `--log-level` command line configuration flag when you start the Sensu agent. +For example, to specify `debug` as the log level: + +{{< code shell >}} +sensu-agent start --log-level debug +{{< /code >}} + +To configure an environment variable for the desired agent log level: + +{{< language-toggle >}} + +{{< code shell "Debian family" >}} +echo 'SENSU_LOG_LEVEL=debug' | sudo tee -a /etc/default/sensu-agent +{{< /code >}} + +{{< code shell "RHEL family" >}} +echo 'SENSU_LOG_LEVEL=debug' | sudo tee -a /etc/sysconfig/sensu-agent +{{< /code >}} + +{{< /language-toggle >}} + +To configure the desired log level in the config file, add this line to agent.yml: + +{{< code shell >}} +log-level: debug +{{< /code >}} + +## Service management + +{{% notice note %}} +**NOTE**: Service management commands may require administrative privileges. +{{% /notice %}} + +### Start the service + +Use the `sensu-agent` tool to start the agent and apply configuration flags. + +{{< platformBlock "Linux" >}} + +**Linux** + +Start the agent with [configuration flags][24]: + +{{< code shell >}} +sensu-agent start --subscriptions disk-checks --log-level debug +{{< /code >}} + +View available configuration flags and defaults: + +{{< code shell >}} +sensu-agent start --help +{{< /code >}} + +Start the agent using a service manager: + +{{< code shell >}} +sudo systemctl start sensu-agent +{{< /code >}} + +If you do not provide any configuration flags, the agent loads configuration from the location specified by the `config-file` attribute (default is `/etc/sensu/agent.yml`). + +{{< platformBlockClose >}} + +{{< platformBlock "Windows" >}} + +**Windows** + +Run the following command as the admin user to install and start the agent: + +{{< code shell >}} +sensu-agent service install +{{< /code >}} + +By default, the agent loads configuration from `%ALLUSERSPROFILE%\sensu\config\agent.yml` (for example, `C:\ProgramData\sensu\config\agent.yml`) and stores service logs to `%ALLUSERSPROFILE%\sensu\log\sensu-agent.log` (for example, `C:\ProgramData\sensu\log\sensu-agent.log`). + +Configure the configuration file and log file locations using the `config-file` and `log-file` flags: + +{{< code shell >}} +sensu-agent service install --config-file 'C:\\ProgramData\\sensu\\config\\agent.yml' --log-file 'C:\\ProgramData\\sensu\\log\\sensu-agent.log' +{{< /code >}} + +{{< platformBlockClose >}} + +### Stop the service + +Stop the agent service using a service manager: + +{{< language-toggle >}} + +{{< code shell "Linux" >}} +sudo systemctl stop sensu-agent +{{< /code >}} + +{{< code shell "Windows" >}} +sc.exe stop SensuAgent +{{< /code >}} + +{{< /language-toggle >}} + +### Restart the service + +You must restart the agent to implement any configuration updates. + +{{< platformBlock "Linux" >}} + +**Linux** + +Restart the agent with a service manager: + +{{< code shell >}} +sudo systemctl restart sensu-agent +{{< /code >}} + +{{< platformBlockClose >}} + +{{< platformBlock "Windows" >}} + +**Windows** + +Restart the agent with a service manager: + +{{< code shell >}} +sc.exe start SensuAgent +{{< /code >}} + +On Windows platforms, the Sensu Agent service will automatically restart after failures. +You'll still need to use a service manager restart Windows agents to implement configuration updates. + +{{< platformBlockClose >}} + +### Enable on boot + +Enable the agent to start on system boot: + +{{< language-toggle >}} + +{{< code shell "Linux" >}} +sudo systemctl enable sensu-agent +{{< /code >}} + +{{< code shell "Windows" >}} +The service is configured to start automatically on boot by default. +{{< /code >}} + +{{< /language-toggle >}} + +{{% notice note %}} +**NOTE**: On older distributions of Linux, use `sudo chkconfig sensu-agent on` to enable the agent. +{{% /notice %}} + +### Disable on boot + +Disable the agent from starting on system boot: + +{{< language-toggle >}} + +{{< code shell "Linux" >}} +sudo systemctl disable sensu-agent +{{< /code >}} + +{{< code shell "Windows" >}} +The service is configured to start automatically on boot by default. +{{< /code >}} + +{{< /language-toggle >}} + +{{% notice note %}} +**NOTE**: On older distributions of Linux, use `sudo chkconfig sensu-agent off` to disable the agent. +{{% /notice %}} + +### Get service status + +View the status of the agent service using a service manager: + +{{< language-toggle >}} + +{{< code shell "Linux" >}} +sudo systemctl status sensu-agent +{{< /code >}} + +{{< code shell "Windows" >}} +sc.exe query SensuAgent +{{< /code >}} + +{{< /language-toggle >}} + +### Get service version + +Get the version of the current `sensu-agent` tool: + +{{< code shell >}} +sensu-agent version +{{< /code >}} + +Get the version of the running `sensu-agent` service: + +{{< code shell >}} +curl http://127.0.0.1:3031/version +{{< /code >}} + +### Uninstall the service + +Uninstall the sensu-agent service: + +{{< language-toggle >}} + +{{< code shell "Linux" >}} +sudo systemctl stop sensu-agent +{{< /code >}} + +{{< code shell "Windows" >}} +sensu-agent service uninstall +{{< /code >}} + +{{< /language-toggle >}} + +### Get help + +The `sensu-agent` tool provides general and command-specific help flags. + +View sensu-agent commands: + +{{< code shell >}} +sensu-agent help +{{< /code >}} + +List options for a specific command (in this case, `sensu-agent start`): + +{{< code shell >}} +sensu-agent start --help +{{< /code >}} + + +[1]: ../../../operations/deploy-sensu/install-sensu#install-sensu-agents +[2]: ../backend/ +[3]: ../../observe-entities/entities/ +[4]: #keepalive-configuration +[5]: ../../../files/windows/agent.yml +[6]: ../../../sensuctl/ +[7]: ../../observe-events/events/ +[8]: ../../observe-process/handlers/ +[9]: ../../observe-filter/filters/ +[10]: ../../observe-transform/mutators/ +[11]: ../../observe-entities/auto-register-deregister/ +[13]: #ephemeral-agent-configuration +[14]: ../checks/ +[15]: https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern +[16]: #general-configuration +[17]: #socket-configuration +[18]: #api-configuration +[19]: https://sourceforge.net/projects/netcat/ +[20]: https://en.wikipedia.org/wiki/Dead_man%27s_switch +[21]: https://github.com/etsy/statsd +[22]: #statsd-configuration +[23]: https://github.com/statsd/statsd#key-concepts +[24]: #command-line-flags +[25]: ../../../api/#response-filtering +[26]: ../../../sensuctl/filter-responses/ +[27]: ../tokens/ +[28]: ../subscriptions/ +[29]: ../../../plugins/assets/ +[30]: #cache-dir +[31]: ../hooks/ +[32]: ../checks/#proxy-entity-name-attribute +[33]: ../../observe-entities/monitor-external-resources/ +[34]: #backend-heartbeat-interval +[35]: ../backend/#datastore-and-cluster-configuration +[36]: ../../../operations/deploy-sensu/cluster-sensu/ +[37]: ../backend/#deregistration-handler-attribute +[38]: #name +[39]: ../../../operations/control-access/rbac/#agent-user +[40]: ../../observe-process/send-slack-alerts/ +[41]: ../../observe-process/handlers/#send-registration-events +[42]: #backend-heartbeat-timeout +[43]: #backend-handshake-timeout +[44]: ../checks#ttl-attribute +[45]: https://en.m.wikipedia.org/wiki/WebSocket +[46]: ../../../operations/deploy-sensu/secure-sensu/ +[47]: https://en.m.wikipedia.org/wiki/Protocol_Buffers +[48]: #example-allow-list-configuration +[49]: #allow-list-configuration +[50]: #environment-variables +[51]: #events-post-specification +[52]: ../../observe-process/handlers/#keepalive-event-handlers +[53]: #keepalive-handlers-option +[54]: ../../../web-ui/search#search-for-labels +[56]: #allow-list +[57]: ../../observe-filter/filters#filter-to-reduce-alert-fatigue-for-keepalive-events +[58]: #keepalive-warning-timeout-option +[59]: ../../../operations/control-access/#use-built-in-basic-authentication +[60]: #log-level +[61]: #retry-min +[62]: #retry-multiplier +[63]: ../../observe-process/pipelines/ +[64]: #keepalive-pipelines-flag +[65]: ../../../sensuctl/create-manage-resources/#supported-resource-types +[66]: #keepalive-pipelines +[67]: #keepalive-handlers +[68]: #create-configuration-overrides +[69]: #agent-configuration-file +[70]: #agent-configuration-methods +[71]: https://en.wikipedia.org/wiki/Configuration_management_database diff --git a/content/sensu-go/6.12/observability-pipeline/observe-schedule/augment-event-data-with-hooks.md b/content/sensu-go/6.12/observability-pipeline/observe-schedule/augment-event-data-with-hooks.md new file mode 100644 index 0000000000..230f2f7376 --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-schedule/augment-event-data-with-hooks.md @@ -0,0 +1,443 @@ +--- +title: "Augment event data with check hooks" +linkTitle: "Augment Event Data" +guide_title: "Augment event data with check hooks" +type: "guide" +description: "Free up precious operator time: use Sensu check hooks to automate data collection that operators would otherwise perform manually to investigate alerts." +weight: 140 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: observe-schedule +--- + +Check hooks are commands the Sensu agent runs in response to the result of check execution. +The Sensu agent executes the appropriate configured hook command based on the exit status code of the check (for example, `1`). + +Check hooks allow you to automate data collection that operators would routinely perform to investigate observability alerts, which frees up precious operator time. +Although you can use check hooks for rudimentary auto-remediation tasks, they are intended to enrich observability event data. + +Follow this guide to create a check hook that captures the process tree if a check returns a status of `2` (critical, not running). + +## Requirements + +To follow this guide, install the Sensu [backend][2], make sure at least one Sensu [agent][14] is running, and install and configure [sensuctl][15]. + +The hook you will create in this guide relies on the `nginx_service` check created in the [Monitor server resources][16] guide. +Before you begin, add the [sensu/sensu-processes-check][12] dynamic runtime asset and [`nginx_service` check][13]. + +## Configure a Sensu entity + +Every Sensu agent has a defined set of subscriptions that determine which checks the agent will execute. +For an agent to execute a specific check, you must specify the same subscription in the agent configuration and the check definition. +To run the `nginx_service` check used as an example in this guide, you'll need a Sensu entity with the subscription `webserver`. + +To add the `webserver` subscription to the entity the Sensu agent is observing, first find your agent entity name: + +{{< code shell >}} +sensuctl entity list +{{< /code >}} + +The `ID` is the name of your entity. + +Replace `` with the name of your agent entity in the following [sensuctl][4] command. +Run: + +{{< code shell >}} +sensuctl entity update +{{< /code >}} + +- For `Entity Class`, press enter. +- For `Subscriptions`, type `webserver` and press enter. + +Confirm both Sensu services are running: + +{{< code shell >}} +systemctl status sensu-backend && systemctl status sensu-agent +{{< /code >}} + +The response should indicate `active (running)` for both the Sensu backend and agent. + +## Install and configure NGINX + +The `nginx_service` check requires a running NGINX service, so you'll need to install and configure NGINX. + +{{% notice note %}} +**NOTE**: You may need to install and update the EPEL repository with `sudo yum install epel-release` and `sudo yum update` before you can install NGINX. +{{% /notice %}} + +Install NGINX: + +{{< code shell >}} +sudo yum install nginx +{{< /code >}} + +Enable and start the NGINX service: + +{{< code shell >}} +systemctl enable nginx && systemctl start nginx +{{< /code >}} + +Verify that NGINX is serving webpages: + +{{< code shell >}} +curl -sI http://localhost +{{< /code >}} + +The response should include `HTTP/1.1 200 OK` to indicate that NGINX processed your request as expected: + +{{< code text >}} +HTTP/1.1 200 OK +Server: nginx/1.20.1 +Date: Wed, 06 Oct 2021 19:35:14 GMT +Content-Type: text/html +Content-Length: 4833 +Last-Modified: Fri, 16 May 2014 15:12:48 GMT +Connection: keep-alive +ETag: "xxxxxxxx-xxxx" +Accept-Ranges: bytes +{{< /code >}} + +With your NGINX service running, you can configure the hook. + +## Create a hook + +Create a new hook that runs a specific command to capture the process tree: + +{{< code shell >}} +sensuctl hook create process_tree \ +--command 'ps aux' \ +--timeout 10 +{{< /code >}} + +To confirm that the hook was added, run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl hook info process_tree --format yaml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl hook info process_tree --format wrapped-json +{{< /code >}} + +{{< /language-toggle >}} + +The response will include the complete hook resource definition in the specified format: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: HookConfig +api_version: core/v2 +metadata: + name: process_tree +spec: + command: ps aux + runtime_assets: null + stdin: false + timeout: 10 +{{< /code >}} + +{{< code json >}} +{ + "type": "HookConfig", + "api_version": "core/v2", + "metadata": { + "name": "process_tree" + }, + "spec": { + "command": "ps aux", + "runtime_assets": null, + "stdin": false, + "timeout": 10 + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Assign the hook to a check + +Now that you've created the `process_tree` hook, you can assign it to the `nginx_service` check. +Setting the `type` to `critical` ensures that whenever the check command returns a critical status, Sensu executes the `process_tree` hook and adds the output to the resulting event data. + +To assign the hook to your `nginx_service` check, run: + +{{< code shell >}} +sensuctl check set-hooks nginx_service \ +--type critical \ +--hooks process_tree +{{< /code >}} + +Examine the check definition to confirm that it includes the hook. +Run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl check info nginx_service --format yaml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl check info nginx_service --format wrapped-json +{{< /code >}} + +{{< /language-toggle >}} + +You should find the `process_tree` hook listed in the `check_hooks` array, within the `critical` array: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: nginx_service +spec: + check_hooks: + - critical: + - process_tree + command: | + sensu-processes-check --search '[{"search_string": "nginx"}]' + env_vars: null + handlers: [] + high_flap_threshold: 0 + interval: 15 + low_flap_threshold: 0 + output_metric_format: "" + output_metric_handlers: null + pipelines: [] + proxy_entity_name: "" + publish: true + round_robin: false + runtime_assets: + - sensu-processes-check + secrets: null + stdin: false + subdue: null + subscriptions: + - webserver + timeout: 0 + ttl: 0 +{{< /code >}} + +{{< code json >}} +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "nginx_service" + }, + "spec": { + "check_hooks": [ + { + "critical": [ + "process_tree" + ] + } + ], + "command": "sensu-processes-check --search '[{\"search_string\": \"nginx\"}]'\n", + "env_vars": null, + "handlers": [], + "high_flap_threshold": 0, + "interval": 15, + "low_flap_threshold": 0, + "output_metric_format": "", + "output_metric_handlers": null, + "pipelines": [], + "proxy_entity_name": "", + "publish": true, + "round_robin": false, + "runtime_assets": [ + "sensu-processes-check" + ], + "secrets": null, + "stdin": false, + "subdue": null, + "subscriptions": [ + "webserver" + ], + "timeout": 0, + "ttl": 0 + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Simulate a critical event + +After you confirm that the hook is attached to your check, stop the NGINX service to observe the check hook in action on the next check execution. + +To manually generate a critical event for your `nginx_service` check, run: + +{{< code shell >}} +systemctl stop nginx +{{< /code >}} + +When you stop the service, the check will generate a critical event. +After a few moments, run: + +{{< code shell >}} +sensuctl event list +{{< /code >}} + +The response should list the `nginx_service` check, returning a CRITICAL status (`2`): + +{{< code text >}} + Entity Check Output Status Silenced Timestamp UUID +─────────────── ─────────────── ──────────────────────────────────────────────────────────────────────── ──────── ────────── ─────────────────────────────── ─────────────────────────────────────── + sensu-centos nginx_service CRITICAL | 0 >= 1 (found >= required) evaluated false for "nginx" 2 false 2021-11-08 17:02:04 +0000 UTC xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + Status - CRITICAL +{{< /code >}} + +## Validate the check hook + +Verify that the check hook is behaving properly against a specific event with `sensuctl`. +To view the check hook command result within an event, replace in the following command with the name of your entity and run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl event info nginx_service --format yaml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl event info nginx_service --format wrapped-json +{{< /code >}} + +{{< /language-toggle >}} + +The check hook command result is available in the `hooks` array, within the `check` scope: + +{{< language-toggle >}} + +{{< code yml >}} +check: + ... + hooks: + - command: ps aux + duration: 0.00747112 + executed: 1645555463 + issued: 0 + metadata: + name: process_tree + output: | + USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND + sensu 17638 0.0 0.1 155452 1860 ? R 18:44 0:00 ps aux + ... + runtime_assets: null + status: 0 + stdin: false + timeout: 10 + ... +{{< /code >}} + +{{< code json >}} +{ + "check": { + "...": "...", + "hooks": [ + { + "command": "ps aux", + "duration": 0.00747112, + "executed": 1645555463, + "issued": 0, + "metadata": { + "name": "process_tree" + }, + "output": "USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND\nsensu 17638 0.0 0.1 155452 1860 ? R 18:44 0:00 ps aux\n", + "...": "...", + "runtime_assets": null, + "status": 0, + "stdin": false, + "timeout": 10 + } + ], + "...": "..." + } +} +{{< /code >}} + +{{< /language-toggle >}} + +You can use sensuctl to query event info and send the response to `jq` so you can isolate the check hook output. +In the following command, replace `` with the name of your entity and run: + +{{< code shell >}} +sensuctl event info nginx_service --format json | jq -r '.check.hooks[0].output' +{{< /code >}} + +This example output is truncated for brevity, but it reflects the output of the `ps aux` command specified in the check hook you created: + +{{< code text >}} +USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND +root 1 0.0 0.3 46164 6704 ? Ss Nov17 0:11 /usr/lib/systemd/systemd --switched-root --system --deserialize 20 +root 2 0.0 0.0 0 0 ? S Nov17 0:00 [kthreadd] +root 3 0.0 0.0 0 0 ? S Nov17 0:01 [ksoftirqd/0] +root 7 0.0 0.0 0 0 ? S Nov17 0:01 [migration/0] +root 8 0.0 0.0 0 0 ? S Nov17 0:00 [rcu_bh] +root 9 0.0 0.0 0 0 ? S Nov17 0:34 [rcu_sched] +{{< /code >}} + +You can also view check hook command results in the web UI. +On the Events page, click the `nginx_service` event for your entity. +Scroll down to the `HOOK` section and click it to expand and review hook command results. + +{{< figure src="/images/go/augment_event_data/hook_command_results_webui.gif" alt="Hook command results displayed in the Sensu web UI" link="/images/go/augment_event_data/hook_command_results_webui.gif" target="_blank" >}} + +Restart the NGINX service to clear the event: + +{{< code shell >}} +systemctl start nginx +{{< /code >}} + +After a moment, you can verify that the event cleared: + +{{< code shell >}} +sensuctl event list +{{< /code >}} + +The response should list the `nginx_service` check with an OK status (`0`). + +Now when you are alerted that NGINX is not running, you can review the check hook output to confirm this is true with no need to start up an SSH session to investigate. + +## What's next + +To learn more about data collection with check hooks, read the [hooks reference][1]. + +Read the [subscriptions reference][3] to learn more about Sensu's publish/subscribe model. + +Create [pipelines][11] with [event filters][9], [mutators][10], and [handlers][5] to send the event data your checks generate to another service for analysis, tracking, and long-term storage. +For example: + +- [Send data to Sumo Logic with Sensu][6] +- [Send PagerDuty alerts with Sensu][7] +- [Send Slack alerts with a pipeline][8] + +In this guide, you used sensuctl to view your check definition, but you can also [view complete resource definitions in the Sensu web UI][17]. + + +[1]: ../hooks/ +[2]: ../../../operations/deploy-sensu/install-sensu/#install-the-sensu-backend +[3]: ../subscriptions/ +[4]: ../../../sensuctl/ +[5]: ../../observe-process/handlers/ +[6]: ../../observe-process/send-data-sumo-logic/ +[7]: ../../observe-process/send-pagerduty-alerts/ +[8]: ../../observe-process/send-slack-alerts/ +[9]: ../../observe-filter/filters/ +[10]: ../../observe-transform/mutators/ +[11]: ../../observe-process/pipelines/ +[12]: ../monitor-server-resources/#register-the-sensusensu-processes-check-asset +[13]: ../monitor-server-resources/#create-the-webserver-check-definition +[14]: ../../../operations/deploy-sensu/install-sensu/#install-sensu-agents +[15]: ../../../operations/deploy-sensu/install-sensu/#install-sensuctl +[16]: ../monitor-server-resources/ +[17]: ../../../web-ui/view-manage-resources/#view-resource-data-in-the-web-ui diff --git a/content/sensu-go/6.12/observability-pipeline/observe-schedule/backend.md b/content/sensu-go/6.12/observability-pipeline/observe-schedule/backend.md new file mode 100644 index 0000000000..60f3587cde --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-schedule/backend.md @@ -0,0 +1,2039 @@ +--- +title: "Backend reference" +linkTitle: "Backend Reference" +reference_title: "Backend" +type: "reference" +description: "Read this reference to learn how Sensu's backend manages check requests and event data by applying filters, mutators, handlers, and the Sensu API and web UI." +weight: 20 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: observe-schedule +--- + +[Example Sensu backend configuration file](../../../files/backend.yml) (download) + +The Sensu backend is a service that manages check requests and observability data. +Every Sensu backend includes an integrated structure for scheduling checks using [subscriptions][28], an event processing pipeline that applies [event filters][9], [mutators][10], [handlers][11], and [pipelines][70], an embedded [etcd][2] datastore for storing configuration and state, and the Sensu [API][14], Sensu [web UI][6], and [sensuctl][37] command line tool. + +The Sensu backend is available for Debian- and RHEL-family distributions of Linux. +For these operating systems, the Sensu backend uses the Bourne shell (sh) for the execution environment. + +Read the [installation guide][1] to install the backend. + +## Initialization + +For a **new** installation, the backend database must be initialized by providing a username and password for the user to be granted administrative privileges. +Although initialization is required for every new installation, the implementation differs depending on your method of installation: + +- If you are using Docker, you can use environment variables to override the default admin username (`admin`) and password (`P@ssw0rd!`) during [step 2 of the backend installation process][24]. +- If you are using a Debian- or RHEL-family distribution, you must specify admin credentials during [step 3 of the backend installation process][25]. +Sensu does not apply default admin credentials for Debian- or RHEL-family installations. + +The initialization step bootstraps the first admin user account for your Sensu installation. +This first account will be granted the cluster admin role. + +{{% notice warning %}} +**WARNING**: If you plan to [run a Sensu cluster](../../../operations/deploy-sensu/cluster-sensu/), make sure that each of your backend nodes is configured, running, and a member of the cluster before you initialize. +{{% /notice %}} + +### Docker initialization + +For Docker installations, set administrator credentials with environment variables when you [configure and start][24] the backend as shown below. +Replace `` and `` with the username and password you want to use: + +{{< language-toggle >}} + +{{< code Docker >}} +docker run -v /var/lib/sensu:/var/lib/sensu \ +-d --name sensu-backend \ +-p 3000:3000 -p 8080:8080 -p 8081:8081 \ +-e SENSU_BACKEND_CLUSTER_ADMIN_USERNAME= \ +-e SENSU_BACKEND_CLUSTER_ADMIN_PASSWORD= \ +sensu/sensu:latest \ +sensu-backend start --state-dir /var/lib/sensu/sensu-backend --log-level debug +{{< /code >}} + +{{< code docker "Docker Compose" >}} +--- +version: "3" +services: + sensu-backend: + ports: + - 3000:3000 + - 8080:8080 + - 8081:8081 + volumes: + - "sensu-backend-data:/var/lib/sensu/sensu-backend/etcd" + command: "sensu-backend start --state-dir /var/lib/sensu/sensu-backend --log-level debug" + environment: + - SENSU_BACKEND_CLUSTER_ADMIN_USERNAME= + - SENSU_BACKEND_CLUSTER_ADMIN_PASSWORD= + image: sensu/sensu:latest + +volumes: + sensu-backend-data: + driver: local +{{< /code >}} + +{{< /language-toggle >}} + +If you did not use environment variables to override the default admin credentials in [step 2 of the backend installation process][24], we recommend [changing your default admin password][26] as soon as you have installed sensuctl. + +### Debian or RHEL family initialization + +For Debian- or RHEL-family distributions, set administrator credentials with environment variables at [initialization][25] as shown below. + +To initialize with your username and password, replace `` and `` with the username and password you want to use: + +{{< code shell >}} +export SENSU_BACKEND_CLUSTER_ADMIN_USERNAME= +export SENSU_BACKEND_CLUSTER_ADMIN_PASSWORD= +sensu-backend init +{{< /code >}} + +{{% notice note %}} +**NOTE**: Make sure the Sensu backend is running before you run `sensu-backend init`. +{{% /notice %}} + +### Add API key for initialization + +Add an [API key][39] when you initialize the backend to make automated cluster setup and deployment more straightforward. +An API key is a persistent UUID that maps to a stored Sensu username. + +If you supply an API key via sensu-backend init, you do not need to configure sensuctl. +Instead, you can execute sensuctl commands to manage resources immediately after initializing a cluster by providing the [`--api-key` and `--api-url` flags][64] with their correct values in your sensuctl commands. + +To initialize with an API key in addition to username and password, set your administrator credentials as follows. +Replace `` with the API key you want to use: + +{{< language-toggle >}} + +{{< code Docker >}} +docker run -v /var/lib/sensu:/var/lib/sensu \ +-d --name sensu-backend \ +-p 3000:3000 -p 8080:8080 -p 8081:8081 \ +-e SENSU_BACKEND_CLUSTER_ADMIN_USERNAME= \ +-e SENSU_BACKEND_CLUSTER_ADMIN_PASSWORD= \ +-e SENSU_BACKEND_CLUSTER_ADMIN_API_KEY= \ +sensu/sensu:latest \ +sensu-backend start --state-dir /var/lib/sensu/sensu-backend --log-level debug +{{< /code >}} + +{{< code docker "Docker Compose" >}} +--- +version: "3" +services: + sensu-backend: + ports: + - 3000:3000 + - 8080:8080 + - 8081:8081 + volumes: + - "sensu-backend-data:/var/lib/sensu/sensu-backend/etcd" + command: "sensu-backend start --state-dir /var/lib/sensu/sensu-backend --log-level debug" + environment: + - SENSU_BACKEND_CLUSTER_ADMIN_USERNAME= + - SENSU_BACKEND_CLUSTER_ADMIN_PASSWORD= + - SENSU_BACKEND_CLUSTER_ADMIN_API_KEY= + image: sensu/sensu:latest + +volumes: + sensu-backend-data: + driver: local +{{< /code >}} + +{{< code shell "Debian and RHEL families" >}} +export SENSU_BACKEND_CLUSTER_ADMIN_USERNAME= +export SENSU_BACKEND_CLUSTER_ADMIN_PASSWORD= +export SENSU_BACKEND_CLUSTER_ADMIN_API_KEY= +sensu-backend init +{{< /code >}} + +{{< /language-toggle >}} + +### Initialize in interactive mode + +You can also run the `sensu-backend init` command in interactive mode: + +{{< code shell >}} +sensu-backend init --interactive +{{< /code >}} + +You will receive prompts for username, password, and API key in interactive mode. +Provide your username and password to complete initialization. +The API key is optional — press `return` to skip it. + +{{< code text >}} +Cluster Admin Username: +Cluster Admin Password: +Retype Cluster Admin Password: +Cluster Admin API Key: +{{< /code >}} + +{{% notice note %}} +**NOTE**: If you are already using Sensu, you do not need to initialize. +Your installation has already seeded the admin username and password you have set up. +Running `sensu-backend init` on a previously initialized cluster has no effect — it will not change the admin credentials. +{{% /notice %}} + +### Initialization flags + +To view available initialization flags: + +{{< code shell >}} +sensu-backend init --help +{{< /code >}} + +The response will list command information and configuration flags for `sensu-backend init`: + +{{< code text >}} +Usage: + sensu-backend init [flags] + +General Flags: + --cluster-admin-api-key string cluster admin API key + --cluster-admin-password string cluster admin password + --cluster-admin-username string cluster admin username + -c, --config-file string path to sensu-backend config file (default "/etc/sensu/backend.yml") + -h, --help help for init + --ignore-already-initialized exit 0 if the cluster has already been initialized + --interactive interactive mode + --timeout string duration to wait before a connection attempt to etcd is considered failed (must be >= 1s) (default "5s") + --wait continuously retry to establish a connection to etcd until it is successful + +Store Flags: + --etcd-advertise-client-urls strings list of this member's client URLs to advertise to clients (default [http://localhost:2379]) + --etcd-cert-file string path to the client server TLS cert file + --etcd-cipher-suites strings list of ciphers to use for etcd TLS configuration + --etcd-client-cert-auth enable client cert authentication + --etcd-client-urls string client URLs to use when operating as an etcd client + --etcd-key-file string path to the client server TLS key file + --etcd-max-request-bytes uint maximum etcd request size in bytes (use with caution) (default 1572864) + --etcd-trusted-ca-file string path to the client server TLS trusted CA cert file +{{< /code >}} + +For more information about the initialization store flags, read [Datastore and cluster configuration][72] and [Advanced configuration options][73]. + + + +| ignore-already-initialized | | +-------------|------ +description | If you run sensu-backend init on a cluster that has already been initialized, the command returns a non-zero exit status. Add the `ignore-already-initialized` flag to suppress the "already initialized" response and return an exit code 0 if the cluster has already been initialized. +example | {{< code shell >}} +sensu-backend init --ignore-already-initialized{{< /code >}} + + + +| timeout | | +-------------|------ +description | Specify how long the backend should continue trying to establish a connection to etcd before timing out.

    To specify the timeout duration, use an integer paired with a unit of time: `s` for seconds, `m` for minutes, or `h` for hours. {{% notice note %}} +**NOTE**: Sensu interprets timeout values less than 1 second and integer-only values as seconds. For example, Sensu will convert both `20ms` and `20` to `20s` (20 seconds).{{% /notice %}} +type | String +example | {{< code shell >}} +sensu-backend init --timeout 30s{{< /code >}} + +| wait | | +-------------|------ +description | Instruct the backend to continue trying to establish a connection to etcd until it is successful. +example | {{< code shell >}} +sensu-backend init --wait{{< /code >}} + +## Backend transport + +The Sensu backend listens for agent communications via [WebSocket][30] transport. +By default, this transport operates on port 8081. +The agent [subscriptions][28] are used to determine which check execution requests the backend publishes via the transport. +Sensu agents locally execute checks as requested by the backend and publish check results back to the transport to be processed. + +Sensu agents authenticate to the Sensu backend via transport by either [built-in username and password authentication][34] or [mutual transport layer security (mTLS) authentication][31]. + +To secure the WebSocket transport, first [generate the certificates][32] you will need to set up transport layer security (TLS). +Then, [secure Sensu][33] by configuring either TLS or mTLS to make Sensu production-ready. + +Read the [Sensu architecture overview][35] for a diagram that includes the WebSocket transport. + +### Certificate bundles or chains + +The Sensu backend supports all types of certificate bundles (or chains) as long as the server (or leaf) certificate is the *first* certificate in the bundle. +This is because the Go standard library assumes that the first certificate listed in the PEM file is the server certificate — the certificate that the program will use to show its own identity. + +If you send the server certificate alone instead of sending the whole bundle with the server certificate first, you will receive a `certificate not signed by trusted authority` error. +You must present the whole chain to the remote so it can determine whether it trusts the server certificate through the chain. + +### Certificate revocation check + +The Sensu backend checks certificate revocation list (CRL) and Online Certificate Status Protocol (OCSP) endpoints for mutual transport layer security (mTLS), etcd client, and etcd peer connections whose remote sides present X.509 certificates that provide CRL and OCSP revocation information. + +## Startup and backend entities + +When a backend starts up, Sensu automatically checks for a [`sensu-system` namespace][68] (and creates the namespace if it doesn't exist). +Then, Sensu checks the `sensu-system` namespace for an existing entity named after the backend's local hostname. + +- If there is no corresponding entity, Sensu creates a new entity with `entity_class: backend` and populates the entity's system information. +- If there is a corresponding entity, Sensu does nothing further to the existing entity. + +Once the backend entity is created, the backend uses its own entity to report cluster state errors. +Read [backend entities][69] in the entities reference for more information and an example backend entity definition. + +## Synchronize time between agents and the backend + +System clocks between agents and the backend should be synchronized to a central NTP server. +If system time is out of sync, it may cause issues with keepalive, metric, and check alerts. + +## Backend clusters + +You can run the backend as a standalone service, but running a cluster of backends makes Sensu more highly available, reliable, and durable. +Sensu backend clusters build on the [etcd clustering system][2]. +Clustering lets you synchronize data between backends and get the benefits of a highly available configuration. + +To configure a cluster, read [Run a Sensu cluster][13] and review the [datastore configuration options][12]. + +## Create event pipelines + +Sensu backend event pipelines process observation data and execute event filters, mutators, handlers, and pipelines. +These resources are powerful tools to automate your monitoring workflows. + +Read the [event filter][9], [mutator][10], [handler][11], and [pipeline][70] references to learn more about these Sensu resources. +Read [guides][71] like [Reduce alert fatigue with event filters][8] and [Send Slack alerts with handlers][7] for usage examples. + +## Schedule checks + +The backend is responsible for storing check definitions and scheduling check requests. +Check scheduling is subscription-based: the backend sends check requests to [subscriptions][28], where they're picked up by subscribing agents. + +For information about creating and managing checks, read the [checks reference][5] and the guides [Monitor server resources with checks][3] and [Collect metrics with checks][4]. + +## Backend configuration options + +Backend configuration is customizable. +This section describes each configuration option in more detail, including examples for each [configuration method][79]. + +You can customize backend configuration with the [backend configuration file][76], [command line flag arguments][77], or [environment variables][78]. + +{{% notice note %}} +**NOTE**: The backend loads configuration upon startup, so you must restart the backend for any configuration updates to take effect. +{{% /notice %}} + +To view configuration information for the `sensu-backend start` command, run: + +{{< code shell >}} +sensu-backend start --help +{{< /code >}} + +The response will list configuration options as command line flags for `sensu-backend start`: + +{{< code text >}} +start the sensu backend + +Usage: + sensu-backend start [flags] + +General Flags: + --agent-auth-cert-file string TLS certificate in PEM format for agent certificate authentication + --agent-auth-crl-urls strings URLs of CRLs for agent certificate authentication + --agent-auth-key-file string TLS certificate key in PEM format for agent certificate authentication + --agent-auth-trusted-ca-file string TLS CA certificate bundle in PEM format for agent certificate authentication + --agent-burst-limit int agent connections maximum burst size + --agent-host string agent listener host (default "[::]") + --agent-serve-wait-time duration wait time before accepting agent connections on startup + --agent-port int agent listener port (default 8081) + --agent-rate-limit int agent connections maximum rate limit + --agent-write-timeout int timeout in seconds for agent writes (default 15) + --annotations stringToString entity annotations map (default []) + --api-listen-address string address to listen on for api traffic (default "[::]:8080") + --api-serve-wait-time duration wait time before serving API requests on startup + --api-request-limit int maximum API request body size, in bytes (default 512000) + --api-url string url of the api to connect to (default "http://localhost:8080") + --api-write-timeout maximum duration before timing out writes of responses + --assets-burst-limit int asset fetch burst limit (default 100) + --assets-rate-limit float maximum number of assets fetched per second + --cache-dir string path to store cached data (default "/var/cache/sensu/sensu-backend") + --cert-file string TLS certificate in PEM format + -c, --config-file string path to sensu-backend config file (default "/etc/sensu/backend.yml") + --dashboard-cert-file string dashboard TLS certificate in PEM format + --dashboard-host string dashboard listener host (default "[::]") + --dashboard-key-file string dashboard TLS certificate key in PEM format + --dashboard-port int dashboard listener port (default 3000) + --dashboard-write-timeout maximum duration before timing out writes of responses + --debug enable debugging and profiling features + --default-silenced-expiry-time Default expiry time for silenced if not set in minutes + --deregistration-handler string default deregistration handler + --disable-platform-metrics disable platform metrics logging + --enable-cert-revocation-check Boolean flag to enable OCSP & CRL check for certificate during mTLS (default true) + --event-log-buffer-size int buffer size of the event logger (default 100000) + --event-log-buffer-wait string full buffer wait time (default "10ms") + --event-log-file string path to the event log file + --event-log-parallel-encoders used to indicate parallel encoders should be used for event logging + --eventd-buffer-size int number of incoming events that can be buffered (default 100) + --eventd-workers int number of workers spawned for processing incoming events (default 100) + -h, --help help for start + --insecure-skip-tls-verify skip TLS verification (not recommended!) + --jwt-private-key-file string path to the PEM-encoded private key to use to sign JWTs + --jwt-public-key-file string path to the PEM-encoded public key to use to verify JWT signatures + --keepalived-buffer-size int number of incoming keepalives that can be buffered (default 100) + --keepalived-workers int number of workers spawned for processing incoming keepalives (default 100) + --key-file string TLS certificate key in PEM format + --labels stringToString entity labels map (default []) + --log-level string logging level [panic, fatal, error, warn, info, debug, trace] (default "warn") + --log-millisecond-timestamps use millisecond precision timestamps in logging output (default "false") + --max-silenced-expiry-time-allowed Maximum expiry time allowed for silenced in minutes + --metrics-refresh-interval string Go duration value (e.g. 1h5m30s) that governs how often metrics are refreshed. (default "1m") + --pipelined-buffer-size int number of events to handle that can be buffered (default 100) + --pipelined-workers int number of workers spawned for handling events through the event pipeline (default 100) + --platform-metrics-log-file string platform metrics log file path + --platform-metrics-logging-interval string platform metrics logging interval + --require-fips indicates whether fips support should be required in openssl + --trusted-ca-file string TLS CA certificate bundle in PEM format + +Store Flags: + --etcd-advertise-client-urls strings list of this member's client URLs to advertise to clients (default [http://localhost:2379]) + --etcd-cert-file string path to the client server TLS cert file + --etcd-cipher-suites strings list of ciphers to use for etcd TLS configuration + --etcd-client-cert-auth enable client cert authentication + --etcd-client-urls string client URLs to use when operating as an etcd client + --etcd-discovery string discovery URL used to bootstrap the cluster + --etcd-discovery-srv string DNS SRV record used to bootstrap the cluster + --etcd-election-timeout uint time in ms a follower node will go without hearing a heartbeat before attempting to become leader itself (default 3000) + --etcd-heartbeat-interval uint interval in ms with which the etcd leader will notify followers that it is still the leader (default 300) + --etcd-initial-advertise-peer-urls strings list of this member's peer URLs to advertise to the rest of the cluster (default [http://127.0.0.1:2380]) + --etcd-initial-cluster string initial cluster configuration for bootstrapping + --etcd-initial-cluster-state string initial cluster state ("new" or "existing") (default "new") + --etcd-initial-cluster-token string initial cluster token for the etcd cluster during bootstrap + --etcd-key-file string path to the client server TLS key file + --etcd-client-log-level string etcd client logging level [panic, fatal, error, warn, info, debug] (default "error") + --etcd-listen-client-urls strings list of etcd client URLs to listen on (default [http://127.0.0.1:2379]) + --etcd-listen-peer-urls strings list of URLs to listen on for peer traffic (default [http://127.0.0.1:2380]) + --etcd-log-level string etcd server logging level [panic, fatal, error, warn, info, debug] + --etcd-max-request-bytes uint maximum etcd request size in bytes (use with caution) (default 1572864) + --etcd-name string name for this etcd node (default "default") + --etcd-peer-cert-file string path to the peer server TLS cert file + --etcd-peer-client-cert-auth enable peer client cert authentication + --etcd-peer-key-file string path to the peer server TLS key file + --etcd-peer-trusted-ca-file string path to the peer server TLS trusted CA file + --etcd-quota-backend-bytes int maximum etcd database size in bytes (use with caution) (default 4294967296) + --etcd-trusted-ca-file string path to the client server TLS trusted CA cert file + --etcd-unsafe-no-fsync disables fsync, unsafe, may cause data loss + --no-embed-etcd don't embed etcd, use external etcd instead +{{< /code >}} + +The backend requires that the [`state-dir`][75] configuration option is set before starting. +All other required flags have default values. + +For more information about log configuration options, read [Event logging][65] and [Platform metrics logging][66]. + +### General configuration + +| annotations| | +-------------|------ +description | Non-identifying metadata to include with entity data for backend dynamic runtime assets (for example, handler and mutator dynamic runtime assets).{{% notice note %}} +**NOTE**: For annotations that you define in backend.yml, the keys are automatically modified to use all lower-case letters. For example, if you define the annotation `webhookURL: "https://my-webhook.com"` in backend.yml, it will be listed as `webhookurl: "https://my-webhook.com"` in entity definitions.

    Key cases are **not** modified for annotations you define with the `--annotations` command line flag or the `SENSU_BACKEND_ANNOTATIONS` environment variable. +{{% /notice %}} +required | false +type | Map of key-value pairs. Keys and values can be any valid UTF-8 string. +default | `null` +environment variable | `SENSU_BACKEND_ANNOTATIONS` +command line example | {{< code shell >}} +sensu-backend start --annotations sensu.io/plugins/slack/config/webhook-url=https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX +sensu-backend start --annotations example-key="example value" --annotations example-key2="example value" +{{< /code >}} +backend.yml config file example | {{< code shell >}} +annotations: + sensu.io/plugins/slack/config/webhook-url: "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX" +{{< /code >}} + +| api-listen-address | | +-------------|------ +description | Address the API daemon will listen for requests on. +type | String +default | `[::]:8080` +environment variable | `SENSU_BACKEND_API_LISTEN_ADDRESS` +command line example | {{< code shell >}} +sensu-backend start --api-listen-address [::]:8080{{< /code >}} +backend.yml config file example | {{< code shell >}} +api-listen-address: "[::]:8080"{{< /code >}} + + + +| api-request-limit | | +-------------|------ +description | Maximum size for API request bodies. In bytes. +type | Integer +default | `512000` +environment variable | `SENSU_BACKEND_API_REQUEST_LIMIT` +command line example | {{< code shell >}} +sensu-backend start --api-request-limit 1024000{{< /code >}} +backend.yml config file example | {{< code shell >}} +api-request-limit: 1024000{{< /code >}} + + + +| api-serve-wait-time | | +-------------|------ +description | Time to wait after starting the backend before serving API requests. In seconds. +type | String +default | `0s` +environment variable | `SENSU_BACKEND_API_SERVE_WAIT_TIME` +command line example | {{< code shell >}} +sensu-backend start --api-serve-wait-time 10s{{< /code >}} +backend.yml config file example | {{< code shell >}} +api-serve-wait-time: 10s{{< /code >}} + + + +| api-url | | +-------------|------ +description | URL used to connect to the API. +type | String +default | `http://localhost:8080` (Debian and RHEL families)

    `http://$SENSU_HOSTNAME:8080` (Docker){{% notice note %}} +**NOTE**: Docker-only Sensu binds to the hostnames of containers, represented here as `SENSU_HOSTNAME` in Docker default values. +{{% /notice %}} +environment variable | `SENSU_BACKEND_API_URL` +command line example | {{< code shell >}} +sensu-backend start --api-url http://localhost:8080{{< /code >}} +backend.yml config file example | {{< code shell >}} +api-url: "http://localhost:8080"{{< /code >}} + + + +| api-write-timeout | | +-------------|------ +description | Maximum amount of time to wait before timing out on API HTTP server response writes. In milliseconds (`ms`), seconds (`s`), minutes (`m`), or hours (`h`). +type | String +default | `15s` +environment variable | `SENSU_BACKEND_API_WRITE_TIMEOUT` +command line example | {{< code shell >}} +sensu-backend start --api-write-timeout 15s{{< /code >}} +backend.yml config file example | {{< code shell >}} +api-write-timeout: 15s{{< /code >}} + +| assets-burst-limit | | +--------------|------ +description | Maximum amount of burst allowed in a rate interval when fetching dynamic runtime assets. +type | Integer +default | `100` +environment variable | `SENSU_BACKEND_ASSETS_BURST_LIMIT` +command line example | {{< code shell >}} +sensu-backend start --assets-burst-limit 100{{< /code >}} +backend.yml config file example | {{< code shell >}} +assets-burst-limit: 100{{< /code >}} + +| assets-rate-limit | | +--------------|------ +description | Maximum number of dynamic runtime assets to fetch per second. The default value `1.39` is equivalent to approximately 5000 user-to-server requests per hour. +type | Float +default | `1.39` +environment variable | `SENSU_BACKEND_ASSETS_RATE_LIMIT` +command line example | {{< code shell >}} +sensu-backend start --assets-rate-limit 1.39{{< /code >}} +backend.yml config file example | {{< code shell >}} +assets-rate-limit: 1.39{{< /code >}} + +| cache-dir | | +--------------|------ +description | Path to store cached data. +type | String +default | `/var/cache/sensu/sensu-backend` +environment variable | `SENSU_BACKEND_CACHE_DIR` +command line example | {{< code shell >}} +sensu-backend start --cache-dir /var/cache/sensu-backend{{< /code >}} +backend.yml config file example | {{< code shell >}} +cache-dir: "/var/cache/sensu-backend"{{< /code >}} + +| config-file | | +--------------|------ +description | Path to Sensu backend config file. +type | String +default | `/etc/sensu/backend.yml` +environment variable | `SENSU_BACKEND_CONFIG_FILE` +command line example | {{< code shell >}} +sensu-backend start --config-file /etc/sensu/backend.yml +sensu-backend start -c /etc/sensu/backend.yml +{{< /code >}} + + + +| debug | | +------------|------ +description | If `true`, enable debugging and profiling features for use with the [Go pprof package][27]. Otherwise, `false`. +type | Boolean +default | `false` +environment variable | `SENSU_BACKEND_DEBUG` +command line example | {{< code shell >}} +sensu-backend start --debug{{< /code >}} +backend.yml config file example | {{< code shell >}} +debug: true{{< /code >}} + + + +| default-silenced-expiry-time | | +-------------------------------|------ +description | Default expiration time to apply for [silences][82] that do not include the [`expire_at`][81] attribute and therefore would not otherwise expire. In minutes (`m`). +type | String +default | `1440m` +environment variable | `SENSU_BACKEND_DEFAULT_SILENCED_EXPIRY_TIME` +command line example | {{< code shell >}} +sensu-backend start --default-silenced-expiry-time 1440m{{< /code >}} +backend.yml config file example | {{< code shell >}} +default-silenced-expiry-time: 1440m{{< /code >}} + + + +| deregistration-handler | | +-------------------------|------ +description | Name of the default event handler to use when processing agent deregistration events. +type | String +default | `""` +environment variable | `SENSU_BACKEND_DEREGISTRATION_HANDLER` +command line example | {{< code shell >}} +sensu-backend start --deregistration-handler deregister{{< /code >}} +backend.yml config file example | {{< code shell >}} +deregistration-handler: "deregister"{{< /code >}} + +| labels | | +-------------|------ +description | Custom attributes to include with entity data for backend dynamic runtime assets (for example, handler and mutator dynamic runtime assets).{{% notice note %}} +**NOTE**: For labels that you define in backend.yml, the keys are automatically modified to use all lower-case letters. For example, if you define the label `securityZone: "us-west-2a"` in backend.yml, it will be listed as `securityzone: "us-west-2a"` in entity definitions.

    Key cases are **not** modified for labels you define with the `--labels` command line flag or the `SENSU_BACKEND_LABELS` environment variable. +{{% /notice %}} +required | false +type | Map of key-value pairs. Keys can contain only letters, numbers, and underscores and must start with a letter. Values can be any valid UTF-8 string. +default | `null` +environment variable | `SENSU_BACKEND_LABELS` +command line example | {{< code shell >}} +sensu-backend start --labels security_zone=us-west-2a +sensu-backend start --labels example_key1="example value" example_key2="example value" +{{< /code >}} +backend.yml config file example | {{< code shell >}} +labels: + security_zone: "us-west-2a" + example_key1: "example value" + example_key2: "example value" +{{< /code >}} + + + +| log-level | | +-------------|------ +description | Logging level: `panic`, `fatal`, `error`, `warn`, `info`, `debug`, or `trace`. +type | String +default | `warn` +environment variable | `SENSU_BACKEND_LOG_LEVEL` +command line example | {{< code shell >}} +sensu-backend start --log-level debug{{< /code >}} +backend.yml config file example | {{< code shell >}} +log-level: "debug"{{< /code >}} + + + +| log-millisecond-timestamps | | +---------------------------|------ +description | If `true`, use millisecond precision timestamps in logging output. Otherwise, `false`. +type | Boolean +default | `false` +environment variable | `SENSU_BACKEND_LOG_MILLISECOND_TIMESTAMPS` +command line example | {{< code shell >}} +sensu-backend start --log-millisecond-timestamps{{< /code >}} +backend.yml config file example | {{< code shell >}} +log-millisecond-timestamps: true{{< /code >}} + + + +| max-silenced-expiry-time-allowed | | +-----------------------------------|------ +description | Maximum length of time for which silences can be set. In minutes (`m`). +type | String +default | `1440m` +environment variable | `SENSU_BACKEND_MAX_SILENCED_EXPIRY_TIME_ALLOWED` +command line example | {{< code shell >}} +sensu-backend start --max-silenced-expiry-time-allowed 1440m{{< /code >}} +backend.yml config file example | {{< code shell >}} +dmax-silenced-expiry-time-allowed: 1440m{{< /code >}} + + + +| metrics-refresh-interval | | +-------------|------ +description | Interval at which Sensu should refresh metrics. In hours, minutes, seconds, or a combination — for example, `5m`, `1m30s`, and `1h10m30s` are all valid values.{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access the `metrics-refresh-interval` configuration option in the packaged Sensu Go distribution. For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} +type | String +default | `1m` +environment variable | `SENSU_BACKEND_METRICS_REFRESH_INTERVAL` +command line example | {{< code shell >}} +sensu-backend start --metrics-refresh-interval 10s{{< /code >}} +backend.yml config file example | {{< code shell >}} +metrics-refresh-interval: 10s{{< /code >}} + + + +| state-dir | | +-------------|------ +description | Path to Sensu state storage: `/var/lib/sensu/sensu-backend`. +type | String +required | true +environment variable | `SENSU_BACKEND_STATE_DIR` +command line example | {{< code shell >}} +sensu-backend start --state-dir /var/lib/sensu/sensu-backend +sensu-backend start -d /var/lib/sensu/sensu-backend +{{< /code >}} +backend.yml config file example | {{< code shell >}} +state-dir: "/var/lib/sensu/sensu-backend"{{< /code >}} + +### Agent communication configuration + +| agent-auth-cert-file | | +-------------|------ +description | TLS certificate in PEM format for agent certificate authentication. Sensu supports certificate bundles (or chains) as long as the server (or leaf) certificate is the *first* certificate in the bundle. +type | String +default | `""` +environment variable | `SENSU_BACKEND_AGENT_AUTH_CERT_FILE` +command line example | {{< code shell >}} +sensu-backend start --agent-auth-cert-file /path/to/tls/backend-1.pem{{< /code >}} +backend.yml config file example | {{< code shell >}} +agent-auth-cert-file: /path/to/tls/backend-1.pem{{< /code >}} + +| agent-auth-crl-urls | | +-------------|------ +description | URLs of CRLs for agent certificate authentication. The Sensu backend uses this list to perform a revocation check for agent mTLS. +type | String +default | `""` +environment variable | `SENSU_BACKEND_AGENT_AUTH_CRL_URLS` +command line example | {{< code shell >}} +sensu-backend start --agent-auth-crl-urls http://localhost/CARoot.crl{{< /code >}} +backend.yml config file example | {{< code shell >}} +agent-auth-crl-urls: http://localhost/CARoot.crl{{< /code >}} + +| agent-auth-key-file | | +-------------|------ +description | TLS certificate key in PEM format for agent certificate authentication. +type | String +default | `""` +environment variable | `SENSU_BACKEND_AGENT_AUTH_KEY_FILE` +command line example | {{< code shell >}} +sensu-backend start --agent-auth-key-file /path/to/tls/backend-1-key.pem{{< /code >}} +backend.yml config file example | {{< code shell >}} +agent-auth-key-file: /path/to/tls/backend-1-key.pem{{< /code >}} + +| agent-auth-trusted-ca-file | | +-------------|------ +description | TLS CA certificate bundle in PEM format for agent certificate authentication. +type | String +default | `""` +environment variable | `SENSU_BACKEND_AGENT_AUTH_TRUSTED_CA_FILE` +command line example | {{< code shell >}} +sensu-backend start --agent-auth-trusted-ca-file /path/to/tls/ca.pem{{< /code >}} +backend.yml config file example | {{< code shell >}} +agent-auth-trusted-ca-file: /path/to/tls/ca.pem{{< /code >}} + + + +| agent-burst-limit | | +--------------|------ +description | Maximum amount of burst allowed in a rate interval for agent transport WebSocket connections. {{% notice note %}} +**NOTE**: The `agent-burst-limit` configuration flag is deprecated. +{{% /notice %}} {{% notice commercial %}} +**COMMERCIAL FEATURE**: Access the `agent-burst-limit` configuration option in the packaged Sensu Go distribution. For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} +type | Integer +default | `null` +environment variable | `SENSU_BACKEND_AGENT_BURST_LIMIT` +command line example | {{< code shell >}} +sensu-backend start --agent-burst-limit 10{{< /code >}} +backend.yml config file example | {{< code shell >}} +agent-burst-limit: 10{{< /code >}} + +| agent-host | | +---------------|------ +description | Agent listener host. Listens on all IPv4 and IPv6 addresses by default. +type | String +default | `[::]` +environment variable | `SENSU_BACKEND_AGENT_HOST` +command line example | {{< code shell >}} +sensu-backend start --agent-host 127.0.0.1{{< /code >}} +backend.yml config file example | {{< code shell >}} +agent-host: "127.0.0.1"{{< /code >}} + + + +| agent-serve-wait-time | | +-------------|------ +description | Time to wait after starting the backend before accepting agent connections. In seconds. +type | String +default | `0s` +environment variable | `SENSU_BACKEND_AGENT_LISTEN_WAIT_TIME` +command line example | {{< code shell >}} +sensu-backend start --agent-serve-wait-time 10s{{< /code >}} +backend.yml config file example | {{< code shell >}} +agent-serve-wait-time: 10s{{< /code >}} + +| agent-port | | +-------------|------ +description | Agent listener port. +type | Integer +default | `8081` +environment variable | `SENSU_BACKEND_AGENT_PORT` +command line example | {{< code shell >}} +sensu-backend start --agent-port 8081{{< /code >}} +backend.yml config file example | {{< code shell >}} +agent-port: 8081{{< /code >}} + + + +| agent-rate-limit | | +--------------|------ +description | Maximum number of agent transport WebSocket connections per second, per backend.{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access the `agent-rate-limit` configuration option in the packaged Sensu Go distribution. For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} +type | Integer +default | `null` +environment variable | `SENSU_BACKEND_AGENT_RATE_LIMIT` +command line example | {{< code shell >}} +sensu-backend start --agent-rate-limit 10{{< /code >}} +backend.yml config file example | {{< code shell >}} +agent-rate-limit: 10{{< /code >}} + +### Security configuration + +| cert-file | | +-------------|------ +description | Path to the primary backend certificate file. Specifies a fallback SSL/TLS certificate if the `dashboard-cert-file` configuration option is not used. This certificate secures communications between the Sensu web UI and end user web browsers, as well as communication between sensuctl and the Sensu API. Sensu supports certificate bundles (or chains) as long as the server (or leaf) certificate is the *first* certificate in the bundle. +type | String +default | `""` +environment variable | `SENSU_BACKEND_CERT_FILE` +command line example | {{< code shell >}} +sensu-backend start --cert-file /path/to/tls/backend-1.pem{{< /code >}} +backend.yml config file example | {{< code shell >}} +cert-file: "/path/to/tls/backend-1.pem"{{< /code >}} + + + +| enable-cert-revocation-check| | +---------------------------|------ +description | If `true`, enable certificate revocation list (CRL) and Online Certificate Status Protocol (OCSP) [checks for SSL certificate revocation][80]. Otherwise, `false`. +type | Boolean +default | `false` +environment variable | `SENSU_BACKEND_ENABLE_CERT_REVOCATION_CHECK` +command line example | {{< code shell >}} +sensu-backend start --enable-cert-revocation-check{{< /code >}} +backend.yml config file example | {{< code shell >}} +enable-cert-revocation-check: true{{< /code >}} + +| insecure-skip-tls-verify | | +---------------------------|------ +description | If `true`, skip SSL verification. Otherwise, `false`. {{% notice warning %}} +**WARNING**: This configuration option is intended for use in development systems only. Do not use this configuration option in production. +{{% /notice %}} +type | Boolean +default | `false` +environment variable | `SENSU_BACKEND_INSECURE_SKIP_TLS_VERIFY` +command line example | {{< code shell >}} +sensu-backend start --insecure-skip-tls-verify{{< /code >}} +backend.yml config file example | {{< code shell >}} +insecure-skip-tls-verify: true{{< /code >}} + + + +| jwt-private-key-file | | +-------------|------ +description | Path to the PEM-encoded private key to use to sign JSON Web Tokens (JWTs). {{% notice note %}} +**NOTE**: The internal symmetric secret key is used by default to sign all JWTs unless a private key is specified via this attribute. +{{% /notice %}} +type | String +default | `""` +environment variable | `SENSU_BACKEND_JWT_PRIVATE_KEY_FILE` +command line example | {{< code shell >}} +sensu-backend start --jwt-private-key-file /path/to/key/private.pem{{< /code >}} +backend.yml config file example | {{< code shell >}} +jwt-private-key-file: /path/to/key/private.pem{{< /code >}} + +| jwt-public-key-file | | +-------------|------ +description | Path to the PEM-encoded public key to use to verify JSON Web Token (JWT) signatures. {{% notice note %}} +**NOTE**: JWTs signed with the internal symmetric secret key will continue to be verified with that key. +{{% /notice %}} +type | String +default | `""` +environment variable | `SENSU_BACKEND_JWT_PUBLIC_KEY_FILE` +required | false, unless `jwt-private-key-file` is defined +command line example | {{< code shell >}} +sensu-backend start --jwt-public-key-file /path/to/key/public.pem{{< /code >}} +backend.yml config file example | {{< code shell >}} +jwt-public-key-file: /path/to/key/public.pem{{< /code >}} + +| key-file | | +-------------|------ +description | Path to the primary backend key file. Specifies a fallback SSL/TLS key if the `dashboard-key-file` configuration option is not used. This key secures communication between the Sensu web UI and end user web browsers, as well as communication between sensuctl and the Sensu API. +type | String +default | `""` +environment variable | `SENSU_BACKEND_KEY_FILE` +command line example | {{< code shell >}} +sensu-backend start --key-file /path/to/tls/backend-1-key.pem{{< /code >}} +backend.yml config file example | {{< code shell >}} +key-file: "/path/to/tls/backend-1-key.pem"{{< /code >}} + + + +| require-fips | | +------------------|------ +description | Require Federal Information Processing Standard (FIPS) support in OpenSSL. Logs an error at Sensu backend startup if `true` but OpenSSL is not running in FIPS mode. {{% notice note %}} +**NOTE**: The `require-fips` configuration option is only available within the Linux amd64 OpenSSL-linked binary. +[Contact Sensu](https://sensu.io/contact) to request the builds for OpenSSL with FIPS support. +{{% /notice %}} +type | Boolean +default | false +environment variable | `SENSU_BACKEND_REQUIRE_FIPS` +command line example | {{< code shell >}} +sensu-backend start --require-fips{{< /code >}} +backend.yml config file example | {{< code shell >}} +require-fips: true{{< /code >}} + +| trusted-ca-file | | +------------------|------ +description | Path to the primary backend CA file. Specifies a fallback SSL/TLS certificate authority in PEM format used for etcd client (mutual TLS) communication if the `etcd-trusted-ca-file` is not used. This CA file is used in communication between the Sensu web UI and end user web browsers, as well as communication between sensuctl and the Sensu API. +type | String +default | `""` +environment variable | `SENSU_BACKEND_TRUSTED_CA_FILE` +command line example | {{< code shell >}} +sensu-backend start --trusted-ca-file /path/to/tls/ca.pem{{< /code >}} +backend.yml config file example | {{< code shell >}} +trusted-ca-file: "/path/to/tls/ca.pem"{{< /code >}} + +### Web UI configuration + +| dashboard-cert-file | | +-------------|------ +description | Web UI TLS certificate in PEM format. This certificate secures communication with the Sensu web UI. If the `dashboard-cert-file` is not provided in the backend configuration, Sensu uses the certificate specified in the [`cert-file` configuration option](#security-configuration) for the web UI. Sensu supports certificate bundles (or chains) as long as the server (or leaf) certificate is the *first* certificate in the bundle. +type | String +default | `""` +environment variable | `SENSU_BACKEND_DASHBOARD_CERT_FILE` +command line example | {{< code shell >}} +sensu-backend start --dashboard-cert-file /path/to/tls/separate-webui-cert.pem{{< /code >}} +backend.yml config file example | {{< code shell >}} +dashboard-cert-file: "/path/to/tls/separate-webui-cert.pem"{{< /code >}} + +| dashboard-host | | +-----------------|------ +description | Web UI listener host. +type | String +default | `[::]` +environment variable | `SENSU_BACKEND_DASHBOARD_HOST` +command line example | {{< code shell >}} +sensu-backend start --dashboard-host 127.0.0.1{{< /code >}} +backend.yml config file example | {{< code shell >}} +dashboard-host: "127.0.0.1"{{< /code >}} + +| dashboard-key-file | | +-------------|------ +description | Web UI TLS certificate key in PEM format. This key secures communication with the Sensu web UI. If the `dashboard-key-file` is not provided in the backend configuration, Sensu uses the key specified in the [`key-file` configuration option](#security-configuration) for the web UI. +type | String +default | `""` +environment variable | `SENSU_BACKEND_DASHBOARD_KEY_FILE` +command line example | {{< code shell >}} +sensu-backend start --dashboard-key-file /path/to/tls/separate-webui-key.pem{{< /code >}} +backend.yml config file example | {{< code shell >}} +dashboard-key-file: "/path/to/tls/separate-webui-key.pem"{{< /code >}} + +| dashboard-port | | +-----------------|------ +description | Web UI listener port. +type | Integer +default | `3000` +environment variable | `SENSU_BACKEND_DASHBOARD_PORT` +command line example | {{< code shell >}} +sensu-backend start --dashboard-port 3000{{< /code >}} +backend.yml config file example | {{< code shell >}} +dashboard-port: 3000{{< /code >}} + + + +| dashboard-write-timeout | | +-------------|------ +description | Maximum amount of time to wait before timing out on web UI HTTP server response writes. In milliseconds (`ms`), seconds (`s`), minutes (`m`), or hours (`h`). +type | String +default | `15s` +environment variable | `SENSU_BACKEND_DASHBOARD_WRITE_TIMEOUT` +command line example | {{< code shell >}} +sensu-backend start --dashboard-write-timeout 15s{{< /code >}} +backend.yml config file example | {{< code shell >}} +dashboard-write-timeout: 15s{{< /code >}} + +### Datastore and cluster configuration + +| etcd-advertise-client-urls | | +--------------|------ +description | List of this member's client URLs to advertise to the rest of the cluster.{{% notice note %}} +**NOTE**: To use Sensu with an [external etcd cluster](../../../operations/deploy-sensu/cluster-sensu/#use-an-external-etcd-cluster), follow etcd's [clustering guide](https://etcd.io/docs/latest/op-guide/clustering/). +Do not configure external etcd in Sensu via backend command line flags or the backend configuration file (`/etc/sensu/backend.yml`). +{{% /notice %}} +type | List +default | `http://localhost:2379` (Debian and RHEL families)

    `http://$SENSU_HOSTNAME:2379` (Docker){{% notice note %}} +**NOTE**: Docker-only Sensu binds to the hostnames of containers, represented here as `SENSU_HOSTNAME` in Docker default values. +{{% /notice %}} +environment variable | `SENSU_BACKEND_ETCD_ADVERTISE_CLIENT_URLS` +command line example | {{< code shell >}} +sensu-backend start --etcd-advertise-client-urls http://localhost:2378,http://localhost:2379 +sensu-backend start --etcd-advertise-client-urls http://localhost:2378 --etcd-advertise-client-urls http://localhost:2379 +{{< /code >}} +backend.yml config file example | {{< code shell >}} +etcd-advertise-client-urls: + - http://localhost:2378 + - http://localhost:2379 +{{< /code >}} + +| etcd-cert-file | | +-----------------|------ +description | Path to the etcd client API TLS certificate file. Secures communication between the embedded etcd client API and any etcd clients. Sensu supports certificate bundles (or chains) as long as the server (or leaf) certificate is the *first* certificate in the bundle.{{% notice note %}} +**NOTE**: To use Sensu with an [external etcd cluster](../../../operations/deploy-sensu/cluster-sensu/#use-an-external-etcd-cluster), follow etcd's [clustering guide](https://etcd.io/docs/latest/op-guide/clustering/). +Do not configure external etcd in Sensu via backend command line flags or the backend configuration file (`/etc/sensu/backend.yml`). +{{% /notice %}} +type | String +default | `""` +environment variable | `SENSU_BACKEND_ETCD_CERT_FILE` +command line example | {{< code shell >}} +sensu-backend start --etcd-cert-file /path/to/tls/backend-1.pem{{< /code >}} +backend.yml config file example | {{< code shell >}} +etcd-cert-file: "/path/to/tls/backend-1.pem"{{< /code >}} + + + +| etcd-cipher-suites | | +------------------------|------ +description | List of allowed cipher suites for etcd TLS configuration. Sensu supports TLS 1.0-1.2 cipher suites as listed in the [Go TLS documentation][18]. You can use this attribute to defend your TLS servers from attacks on weak TLS ciphers. Go determines the default cipher suites based on the hardware used. {{% notice note %}} +**NOTE**: To use TLS 1.3, add the following environment variable: `GODEBUG="tls13=1"`.

    To use Sensu with an [external etcd cluster](../../../operations/deploy-sensu/cluster-sensu/#use-an-external-etcd-cluster), follow etcd's [clustering guide](https://etcd.io/docs/latest/op-guide/clustering/). +Do not configure external etcd in Sensu via backend command line flags or the backend configuration file (`/etc/sensu/backend.yml`). +{{% /notice %}} +recommended | {{< code shell >}} +etcd-cipher-suites: + - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 + - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 + - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 + - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 + - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305 + - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 +{{< /code >}} +type | List +environment variable | `SENSU_BACKEND_ETCD_CIPHER_SUITES` +command line example | {{< code shell >}} +sensu-backend start --etcd-cipher-suites TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 +sensu-backend start --etcd-cipher-suites TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 --etcd-cipher-suites TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 +{{< /code >}} +backend.yml config file example | {{< code shell >}} +etcd-cipher-suites: + - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 + - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 +{{< /code >}} + +| etcd-client-cert-auth | | +------------------------|------ +description | If `true`, enable client certificate authentication. Otherwise, `false`.{{% notice note %}} +**NOTE**: To use Sensu with an [external etcd cluster](../../../operations/deploy-sensu/cluster-sensu/#use-an-external-etcd-cluster), follow etcd's [clustering guide](https://etcd.io/docs/latest/op-guide/clustering/). +Do not configure external etcd in Sensu via backend command line flags or the backend configuration file (`/etc/sensu/backend.yml`). +{{% /notice %}} +type | Boolean +default | `false` +environment variable | `SENSU_BACKEND_ETCD_CLIENT_CERT_AUTH` +command line example | {{< code shell >}} +sensu-backend start --etcd-client-cert-auth{{< /code >}} +backend.yml config file example | {{< code shell >}} +etcd-client-cert-auth: true{{< /code >}} + + + +| etcd-client-log-level | | +-------------|------ +description | Logging level for the internal etcd client: `panic`, `fatal`, `error`, `warn`, `info`, or `debug`. +type | String +default | `error` +environment variable | `SENSU_BACKEND_ETCD_CLIENT_LOG_LEVEL` +command line example | {{< code shell >}} +sensu-backend start --etcd-client-log-level error{{< /code >}} +backend.yml config file example | {{< code shell >}} +etcd-client-log-level: "error"{{< /code >}} + +| etcd-client-urls | | +------------------------|------ +description | List of client URLs to use when a sensu-backend is not operating as an etcd member. To configure sensu-backend for use with an external etcd instance, use this configuration option in conjunction with `no-embed-etcd` when executing sensu-backend start or [sensu-backend init][22]. If you do not use this option when using `no-embed-etcd`, sensu-backend start and sensu-backend-init will fall back to [--etcd-listen-client-urls][23].{{% notice note %}} +**NOTE**: To use Sensu with an [external etcd cluster](../../../operations/deploy-sensu/cluster-sensu/#use-an-external-etcd-cluster), follow etcd's [clustering guide](https://etcd.io/docs/latest/op-guide/clustering/). +Do not configure external etcd in Sensu via backend command line flags or the backend configuration file (`/etc/sensu/backend.yml`). +{{% /notice %}} +type | List +default | `http://127.0.0.1:2379` +environment variable | `SENSU_BACKEND_ETCD_CLIENT_URLS` +command line example | {{< code shell >}} +sensu-backend start --etcd-client-urls 'https://10.0.0.1:2379 https://10.1.0.1:2379' +sensu-backend start --etcd-client-urls https://10.0.0.1:2379 --etcd-client-urls https://10.1.0.1:2379 +{{< /code >}} +backend.yml config file example | {{< code shell >}} +etcd-client-urls: + - https://10.0.0.1:2379 + - https://10.1.0.1:2379 +{{< /code >}} + + + +| etcd-discovery | | +------------------------|------ +description | Exposes [etcd's embedded auto-discovery features][19]. Attempts to use [etcd discovery][20] to get the cluster configuration.{{% notice note %}} +**NOTE**: To use Sensu with an [external etcd cluster](../../../operations/deploy-sensu/cluster-sensu/#use-an-external-etcd-cluster), follow etcd's [clustering guide](https://etcd.io/docs/latest/op-guide/clustering/). +Do not configure external etcd in Sensu via backend command line flags or the backend configuration file (`/etc/sensu/backend.yml`). +{{% /notice %}} +type | String +default | "" +environment variable | `SENSU_BACKEND_ETCD_DISCOVERY` +command line example | {{< code shell >}} +sensu-backend start --etcd-discovery https://discovery.etcd.io/3e86b59982e49066c5d813af1c2e2579cbf573de{{< /code >}} +backend.yml config file example | {{< code shell >}} +etcd-discovery: + - https://discovery.etcd.io/3e86b59982e49066c5d813af1c2e2579cbf573de +{{< /code >}} + + + +| etcd-discovery-srv | | +------------------------|------ +description | Exposes [etcd's embedded auto-discovery features][17]. Attempts to use a [DNS SRV][21] record to get the cluster configuration.{{% notice note %}} +**NOTE**: To use Sensu with an [external etcd cluster](../../../operations/deploy-sensu/cluster-sensu/#use-an-external-etcd-cluster), follow etcd's [clustering guide](https://etcd.io/docs/latest/op-guide/clustering/). +Do not configure external etcd in Sensu via backend command line flags or the backend configuration file (`/etc/sensu/backend.yml`). +{{% /notice %}} +type | String +default | "" +environment variable | `SENSU_BACKEND_ETCD_DISCOVERY_SRV` +command line example | {{< code shell >}} +sensu-backend start --etcd-discovery-srv example.org{{< /code >}} +backend.yml config file example | {{< code shell >}} +etcd-discovery-srv: + - example.org +{{< /code >}} + +| etcd-initial-advertise-peer-urls | | +-----------------------------------|------ +description | List of this member's peer URLs to advertise to the rest of the cluster.{{% notice note %}} +**NOTE**: To use Sensu with an [external etcd cluster](../../../operations/deploy-sensu/cluster-sensu/#use-an-external-etcd-cluster), follow etcd's [clustering guide](https://etcd.io/docs/latest/op-guide/clustering/). +Do not configure external etcd in Sensu via backend command line flags or the backend configuration file (`/etc/sensu/backend.yml`). +{{% /notice %}} +type | List +default | `http://127.0.0.1:2380` (Debian and RHEL families)

    `http://$SENSU_HOSTNAME:2380` (Docker){{% notice note %}} +**NOTE**: Docker-only Sensu binds to the hostnames of containers, represented here as `SENSU_HOSTNAME` in Docker default values. +{{% /notice %}} +environment variable | `SENSU_BACKEND_ETCD_INITIAL_ADVERTISE_PEER_URLS` +command line example | {{< code shell >}} +sensu-backend start --etcd-initial-advertise-peer-urls https://10.0.0.1:2380,https://10.1.0.1:2380 +sensu-backend start --etcd-initial-advertise-peer-urls https://10.0.0.1:2380 --etcd-initial-advertise-peer-urls https://10.1.0.1:2380 +{{< /code >}} +backend.yml config file example | {{< code shell >}} +etcd-initial-advertise-peer-urls: + - https://10.0.0.1:2380 + - https://10.1.0.1:2380 +{{< /code >}} + +| etcd-initial-cluster | | +-----------------------|------ +description | Initial cluster configuration for bootstrapping.{{% notice note %}} +**NOTE**: To use Sensu with an [external etcd cluster](../../../operations/deploy-sensu/cluster-sensu/#use-an-external-etcd-cluster), follow etcd's [clustering guide](https://etcd.io/docs/latest/op-guide/clustering/). +Do not configure external etcd in Sensu via backend command line flags or the backend configuration file (`/etc/sensu/backend.yml`). +{{% /notice %}} +type | String +default | `default=http://127.0.0.1:2380` (Debian and RHEL families)

    `default=http://$SENSU_HOSTNAME:2380` (Docker){{% notice note %}} +**NOTE**: Docker-only Sensu binds to the hostnames of containers, represented here as `SENSU_HOSTNAME` in Docker default values. +{{% /notice %}} +environment variable | `SENSU_BACKEND_ETCD_INITIAL_CLUSTER` +command line example | {{< code shell >}} +sensu-backend start --etcd-initial-cluster backend-0=https://10.0.0.1:2380,backend-1=https://10.1.0.1:2380,backend-2=https://10.2.0.1:2380{{< /code >}} +backend.yml config file example | {{< code shell >}} +etcd-initial-cluster: "backend-0=https://10.0.0.1:2380,backend-1=https://10.1.0.1:2380,backend-2=https://10.2.0.1:2380"{{< /code >}} + +| etcd-initial-cluster-state | | +-----------------------------|------ +description | Initial cluster state (`new` or `existing`).{{% notice note %}} +**NOTE**: To use Sensu with an [external etcd cluster](../../../operations/deploy-sensu/cluster-sensu/#use-an-external-etcd-cluster), follow etcd's [clustering guide](https://etcd.io/docs/latest/op-guide/clustering/). +Do not configure external etcd in Sensu via backend command line flags or the backend configuration file (`/etc/sensu/backend.yml`). +{{% /notice %}} +type | String +default | `new` +environment variable | `SENSU_BACKEND_ETCD_INITIAL_CLUSTER_STATE` +command line example | {{< code shell >}} +sensu-backend start --etcd-initial-cluster-state existing{{< /code >}} +backend.yml config file example | {{< code shell >}} +etcd-initial-cluster-state: "existing"{{< /code >}} + +| etcd-initial-cluster-token | | +-----------------------------|------ +description | Unique token for the etcd cluster. Provide the same `etcd-initial-cluster-token` value for each cluster member. The `etcd-initial-cluster-token` allows etcd to generate unique cluster IDs and member IDs even for clusters with otherwise identical configurations, which prevents cross-cluster-interaction and potential cluster corruption.{{% notice note %}} +**NOTE**: To use Sensu with an [external etcd cluster](../../../operations/deploy-sensu/cluster-sensu/#use-an-external-etcd-cluster), follow etcd's [clustering guide](https://etcd.io/docs/latest/op-guide/clustering/). +Do not configure external etcd in Sensu via backend command line flags or the backend configuration file (`/etc/sensu/backend.yml`). +{{% /notice %}} +type | String +default | `""` +environment variable | `SENSU_BACKEND_ETCD_INITIAL_CLUSTER_TOKEN` +command line example | {{< code shell >}} +sensu-backend start --etcd-initial-cluster-token unique_token_for_this_cluster{{< /code >}} +backend.yml config file example | {{< code shell >}} +etcd-initial-cluster-token: "unique_token_for_this_cluster"{{< /code >}} + +| etcd-key-file | | +-----------------|------ +description | Path to the etcd client API TLS key file. Secures communication between the embedded etcd client API and any etcd clients.{{% notice note %}} +**NOTE**: To use Sensu with an [external etcd cluster](../../../operations/deploy-sensu/cluster-sensu/#use-an-external-etcd-cluster), follow etcd's [clustering guide](https://etcd.io/docs/latest/op-guide/clustering/). +Do not configure external etcd in Sensu via backend command line flags or the backend configuration file (`/etc/sensu/backend.yml`). +{{% /notice %}} +type | String +environment variable | `SENSU_BACKEND_ETCD_KEY_FILE` +command line example | {{< code shell >}} +sensu-backend start --etcd-key-file /path/to/tls/backend-1-key.pem{{< /code >}} +backend.yml config file example | {{< code shell >}} +etcd-key-file: "/path/to/tls/backend-1-key.pem"{{< /code >}} + + + +| etcd-listen-client-urls | | +--------------------------|------ +description | List of URLs to listen on for client traffic. Sensu's default embedded etcd configuration listens for unencrypted client communication on port 2379.{{% notice note %}} +**NOTE**: To use Sensu with an [external etcd cluster](../../../operations/deploy-sensu/cluster-sensu/#use-an-external-etcd-cluster), follow etcd's [clustering guide](https://etcd.io/docs/latest/op-guide/clustering/). +Do not configure external etcd in Sensu via backend command line flags or the backend configuration file (`/etc/sensu/backend.yml`). +{{% /notice %}} +type | List +default | `http://127.0.0.1:2379` (Debian and RHEL families)

    `http://[::]:2379` (Docker) +environment variable | `SENSU_BACKEND_ETCD_LISTEN_CLIENT_URLS` +command line example | {{< code shell >}} +sensu-backend start --etcd-listen-client-urls https://10.0.0.1:2379,https://10.1.0.1:2379 +sensu-backend start --etcd-listen-client-urls https://10.0.0.1:2379 --etcd-listen-client-urls https://10.1.0.1:2379 +{{< /code >}} +backend.yml config file example | {{< code shell >}} +etcd-listen-client-urls: + - https://10.0.0.1:2379 + - https://10.1.0.1:2379 +{{< /code >}} + +| etcd-listen-peer-urls | | +------------------------|------ +description | List of URLs to listen on for peer traffic. Sensu's default embedded etcd configuration listens for unencrypted peer communication on port 2380.{{% notice note %}} +**NOTE**: To use Sensu with an [external etcd cluster](../../../operations/deploy-sensu/cluster-sensu/#use-an-external-etcd-cluster), follow etcd's [clustering guide](https://etcd.io/docs/latest/op-guide/clustering/). +Do not configure external etcd in Sensu via backend command line flags or the backend configuration file (`/etc/sensu/backend.yml`). +{{% /notice %}} +type | List +default | `http://127.0.0.1:2380` (Debian and RHEL families)

    `http://[::]:2380` (Docker) +environment variable | `SENSU_BACKEND_ETCD_LISTEN_PEER_URLS` +command line example | {{< code shell >}} +sensu-backend start --etcd-listen-peer-urls https://10.0.0.1:2380,https://10.1.0.1:2380 +sensu-backend start --etcd-listen-peer-urls https://10.0.0.1:2380 --etcd-listen-peer-urls https://10.1.0.1:2380 +{{< /code >}} +backend.yml config file example | {{< code shell >}} +etcd-listen-peer-urls: + - https://10.0.0.1:2380 + - https://10.1.0.1:2380 +{{< /code >}} + + + +| etcd-log-level | | +-------------|------ +description | Logging level for the embedded etcd server: `panic`, `fatal`, `error`, `warn`, `info`, or `debug`. Defaults to value provided for the [backend log level][60]. If the backend log level is set to `trace`, the etcd log level will be set to `debug` (`trace` is not a valid etcd log level). +type | String +default | [Backend log level][60] value (or `debug`, if the backend log level is set to `trace`) +environment variable | `SENSU_BACKEND_ETCD_LOG_LEVEL` +command line example | {{< code shell >}} +sensu-backend start --etcd-log-level debug{{< /code >}} +backend.yml config file example | {{< code shell >}} +etcd-log-level: "debug"{{< /code >}} + +| etcd-name | | +-----------------|------ +description | Human-readable name for this member.{{% notice note %}} +**NOTE**: To use Sensu with an [external etcd cluster](../../../operations/deploy-sensu/cluster-sensu/#use-an-external-etcd-cluster), follow etcd's [clustering guide](https://etcd.io/docs/latest/op-guide/clustering/). +Do not configure external etcd in Sensu via backend command line flags or the backend configuration file (`/etc/sensu/backend.yml`). +{{% /notice %}} +type | String +default | `default` +environment variable | `SENSU_BACKEND_ETCD_NAME` +command line example | {{< code shell >}} +sensu-backend start --etcd-name backend-0{{< /code >}} +backend.yml config file example | {{< code shell >}} +etcd-name: "backend-0"{{< /code >}} + +| etcd-peer-cert-file | | +----------------------|------ +description | Path to the peer server TLS certificate file. Sensu supports certificate bundles (or chains) as long as the server (or leaf) certificate is the *first* certificate in the bundle.{{% notice note %}} +**NOTE**: To use Sensu with an [external etcd cluster](../../../operations/deploy-sensu/cluster-sensu/#use-an-external-etcd-cluster), follow etcd's [clustering guide](https://etcd.io/docs/latest/op-guide/clustering/). +Do not configure external etcd in Sensu via backend command line flags or the backend configuration file (`/etc/sensu/backend.yml`). +{{% /notice %}} +type | String +environment variable | `SENSU_BACKEND_ETCD_PEER_CERT_FILE` +command line example | {{< code shell >}} +sensu-backend start --etcd-peer-cert-file /path/to/tls/backend-1.pem{{< /code >}} +backend.yml config file example | {{< code shell >}} +etcd-peer-cert-file: "/path/to/tls/backend-1.pem"{{< /code >}} + +| etcd-peer-client-cert-auth | | +-----------------------------|------ +description | Enable peer client certificate authentication.{{% notice note %}} +**NOTE**: To use Sensu with an [external etcd cluster](../../../operations/deploy-sensu/cluster-sensu/#use-an-external-etcd-cluster), follow etcd's [clustering guide](https://etcd.io/docs/latest/op-guide/clustering/). +Do not configure external etcd in Sensu via backend command line flags or the backend configuration file (`/etc/sensu/backend.yml`). +{{% /notice %}} +type | Boolean +default | `false` +environment variable | `SENSU_BACKEND_ETCD_PEER_CLIENT_CERT_AUTH` +command line example | {{< code shell >}} +sensu-backend start --etcd-peer-client-cert-auth{{< /code >}} +backend.yml config file example | {{< code shell >}} +etcd-peer-client-cert-auth: true{{< /code >}} + +| etcd-peer-key-file | | +---------------------|------ +description | Path to the etcd peer API TLS key file. Secures communication between etcd cluster members.{{% notice note %}} +**NOTE**: To use Sensu with an [external etcd cluster](../../../operations/deploy-sensu/cluster-sensu/#use-an-external-etcd-cluster), follow etcd's [clustering guide](https://etcd.io/docs/latest/op-guide/clustering/). +Do not configure external etcd in Sensu via backend command line flags or the backend configuration file (`/etc/sensu/backend.yml`). +{{% /notice %}} +type | String +environment variable | `SENSU_BACKEND_ETCD_PEER_KEY_FILE` +command line example | {{< code shell >}} +sensu-backend start --etcd-peer-key-file /path/to/tls/backend-1-key.pem{{< /code >}} +backend.yml config file example | {{< code shell >}} +etcd-peer-key-file: "/path/to/tls/backend-1-key.pem"{{< /code >}} + +| etcd-peer-trusted-ca-file | | +----------------------------|------ +description | Path to the etcd peer API server TLS trusted CA file. Secures communication between etcd cluster members.{{% notice note %}} +**NOTE**: To use Sensu with an [external etcd cluster](../../../operations/deploy-sensu/cluster-sensu/#use-an-external-etcd-cluster), follow etcd's [clustering guide](https://etcd.io/docs/latest/op-guide/clustering/). +Do not configure external etcd in Sensu via backend command line flags or the backend configuration file (`/etc/sensu/backend.yml`). +{{% /notice %}} +type | String +environment variable | `SENSU_BACKEND_ETCD_PEER_TRUSTED_CA_FILE` +command line example | {{< code shell >}} +sensu-backend start --etcd-peer-trusted-ca-file ./ca.pem{{< /code >}} +backend.yml config file example | {{< code shell >}} +etcd-peer-trusted-ca-file: "./ca.pem"{{< /code >}} + +| etcd-trusted-ca-file | | +-----------------------|------ +description | Path to the client server TLS trusted CA certificate file. Secures communication with the etcd client server.{{% notice note %}} +**NOTE**: To use Sensu with an [external etcd cluster](../../../operations/deploy-sensu/cluster-sensu/#use-an-external-etcd-cluster), follow etcd's [clustering guide](https://etcd.io/docs/latest/op-guide/clustering/). +Do not configure external etcd in Sensu via backend command line flags or the backend configuration file (`/etc/sensu/backend.yml`). +{{% /notice %}} +type | String +default | `""` +environment variable | `SENSU_BACKEND_ETCD_TRUSTED_CA_FILE` +command line example | {{< code shell >}} +sensu-backend start --etcd-trusted-ca-file ./ca.pem{{< /code >}} +backend.yml config file example | {{< code shell >}} +etcd-trusted-ca-file: "./ca.pem"{{< /code >}} + + + +| etcd-unsafe-no-fsync | | +-----------------------|------ +description | The `etcd-unsafe-no-fsync` configuration option allows you to run sensu-backend with an embedded etcd node for testing and development with less load on the file system. If `true`, disable fsync. Otherwise, `false`. +type | Boolean +default | `false` +environment variable | `SENSU_BACKEND_ETCD_UNSAFE_NO_FSYNC` +command line example | {{< code shell >}} +sensu-backend start --etcd-unsafe-no-fsync{{< /code >}} +backend.yml config file example | {{< code shell >}} +etcd-unsafe-no-fsync: true{{< /code >}} + +| no-embed-etcd | | +-----------------|------ +description | If `true`, do not embed etcd (use external etcd instead). Otherwise, `false`.{{% notice note %}} +**NOTE**: To use Sensu with an [external etcd cluster](../../../operations/deploy-sensu/cluster-sensu/#use-an-external-etcd-cluster), follow etcd's [clustering guide](https://etcd.io/docs/latest/op-guide/clustering/). +Do not configure external etcd in Sensu via backend command line flags or the backend configuration file (`/etc/sensu/backend.yml`). +{{% /notice %}} +type | Boolean +default | `false` +environment variable | `SENSU_BACKEND_NO_EMBED_ETCD` +command line example | {{< code shell >}} +sensu-backend start --no-embed-etcd{{< /code >}} +backend.yml config file example | {{< code shell >}} +no-embed-etcd: true{{< /code >}} + +### Advanced configuration options + + + +| etcd-election-timeout | | +-----------------------|------ +description | Time that a follower node will go without hearing a heartbeat before attempting to become leader itself. In milliseconds (ms). Set to at least 10 times the [etcd-heartbeat-interval][36]. Read the [etcd time parameter documentation][16] for details and other considerations. {{% notice warning %}} +**WARNING**: Make sure to set the same election timeout value for all etcd members in one cluster. Setting different values for etcd members may reduce cluster stability. +{{% /notice %}}{{% notice note %}} +**NOTE**: To use Sensu with an [external etcd cluster](../../../operations/deploy-sensu/cluster-sensu/#use-an-external-etcd-cluster), follow etcd's [clustering guide](https://etcd.io/docs/latest/op-guide/clustering/). +Do not configure external etcd in Sensu via backend command line flags or the backend configuration file (`/etc/sensu/backend.yml`). +{{% /notice %}} +type | Integer +default | `3000` +environment variable | `SENSU_BACKEND_ETCD_ELECTION_TIMEOUT` +command line example | {{< code shell >}} +sensu-backend start --etcd-election-timeout 3000{{< /code >}} +backend.yml config file example | {{< code shell >}} +etcd-election-timeout: 3000{{< /code >}} + + + +| etcd-heartbeat-interval | | +-----------------------|------ +description | Interval at which the etcd leader will notify followers that it is still the leader. In milliseconds (ms). Best practice is to set the interval based on round-trip time between members. Read the [etcd time parameter documentation][16] for details and other considerations. {{% notice warning %}} +**WARNING**: Make sure to set the same heartbeat interval value for all etcd members in one cluster. Setting different values for etcd members may reduce cluster stability.{{% /notice %}}{{% notice note %}} +**NOTE**: To use Sensu with an [external etcd cluster](../../../operations/deploy-sensu/cluster-sensu/#use-an-external-etcd-cluster), follow etcd's [clustering guide](https://etcd.io/docs/latest/op-guide/clustering/). +Do not configure external etcd in Sensu via backend command line flags or the backend configuration file (`/etc/sensu/backend.yml`). +{{% /notice %}} +type | Integer +default | `300` +environment variable | `SENSU_BACKEND_ETCD_HEARTBEAT_INTERVAL` +command line example | {{< code shell >}} +sensu-backend start --etcd-heartbeat-interval 300{{< /code >}} +backend.yml config file example | {{< code shell >}} +etcd-heartbeat-interval: 300{{< /code >}} + +| etcd-max-request-bytes | | +-----------------------|------ +description | Maximum etcd request size in bytes that can be sent to an etcd server by a client. Increasing this value allows etcd to process events with large outputs at the cost of overall latency. {{% notice warning %}} +**WARNING**: Use with caution. This configuration option requires familiarity with etcd. Improper use of this option can result in a non-functioning Sensu instance.{{% /notice %}}{{% notice note %}} +**NOTE**: To use Sensu with an [external etcd cluster](../../../operations/deploy-sensu/cluster-sensu/#use-an-external-etcd-cluster), follow etcd's [clustering guide](https://etcd.io/docs/latest/op-guide/clustering/). +Do not configure external etcd in Sensu via backend command line flags or the backend configuration file (`/etc/sensu/backend.yml`). +{{% /notice %}} +type | Integer +default | `1572864` +environment variable | `SENSU_BACKEND_ETCD_MAX_REQUEST_BYTES` +command line example | {{< code shell >}} +sensu-backend start --etcd-max-request-bytes 1572864{{< /code >}} +backend.yml config file example | {{< code shell >}} +etcd-max-request-bytes: 1572864{{< /code >}} + +| etcd-quota-backend-bytes | | +-----------------------|------ +description | Maximum etcd database size in bytes. Increasing this value allows for a larger etcd database at the cost of performance. {{% notice warning %}} +**WARNING**: Use with caution. This configuration option requires familiarity with etcd. Improper use of this option can result in a non-functioning Sensu instance.{{% /notice %}}{{% notice note %}} +**NOTE**: To use Sensu with an [external etcd cluster](../../../operations/deploy-sensu/cluster-sensu/#use-an-external-etcd-cluster), follow etcd's [clustering guide](https://etcd.io/docs/latest/op-guide/clustering/). +Do not configure external etcd in Sensu via backend command line flags or the backend configuration file (`/etc/sensu/backend.yml`). +{{% /notice %}} +type | Integer +default | `4294967296` +environment variable | `SENSU_BACKEND_ETCD_QUOTA_BACKEND_BYTES` +command line example | {{< code shell >}} +sensu-backend start --etcd-quota-backend-bytes 4294967296{{< /code >}} +backend.yml config file example | {{< code shell >}} +etcd-quota-backend-bytes: 4294967296{{< /code >}} + +| eventd-buffer-size | | +-----------------------|------ +description | Number of incoming events that can be buffered before being processed by an eventd worker. {{% notice warning %}} +**WARNING**: Modify with caution. Increasing this value may result in greater memory usage. +{{% /notice %}} +type | Integer +default | `100` +environment variable | `SENSU_BACKEND_EVENTD_BUFFER_SIZE` +command line example | {{< code shell >}} +sensu-backend start --eventd-buffer-size 100{{< /code >}} +backend.yml config file example | {{< code shell >}} +eventd-buffer-size: 100{{< /code >}} + +| eventd-workers | | +-----------------------|------ +description | Number of workers spawned for processing incoming events that are stored in the eventd buffer. {{% notice warning %}} +**WARNING**: Modify with caution. Increasing this value may result in greater CPU usage. +{{% /notice %}} +type | Integer +default | `100` +environment variable | `SENSU_BACKEND_EVENTD_WORKERS` +command line example | {{< code shell >}} +sensu-backend start --eventd-workers 100{{< /code >}} +backend.yml config file example | {{< code shell >}} +eventd-workers: 100{{< /code >}} + +| keepalived-buffer-size | | +-----------------------|------ +description | Number of incoming keepalives that can be buffered before being processed by a keepalived worker. {{% notice warning %}} +**WARNING**: Modify with caution. Increasing this value may result in greater memory usage. +{{% /notice %}} +type | Integer +default | `100` +environment variable | `SENSU_BACKEND_KEEPALIVED_BUFFER_SIZE` +command line example | {{< code shell >}} +sensu-backend start --keepalived-buffer-size 100{{< /code >}} +backend.yml config file example | {{< code shell >}} +keepalived-buffer-size: 100{{< /code >}} + +| keepalived-workers | | +-----------------------|------ +description | Number of workers spawned for processing incoming keepalives that are stored in the keepalived buffer. {{% notice warning %}} +**WARNING**: Modify with caution. Increasing this value may result in greater CPU usage.{{% /notice %}} +type | Integer +default | `100` +environment variable | `SENSU_BACKEND_KEEPALIVED_WORKERS` +command line example | {{< code shell >}} +sensu-backend start --keepalived-workers 100{{< /code >}} +backend.yml config file example | {{< code shell >}} +keepalived-workers: 100{{< /code >}} + +| pipelined-buffer-size | | +-----------------------|------ +description | Number of events to handle that can be buffered before being processed by a pipelined worker. {{% notice warning %}} +**WARNING**: Modify with caution. Increasing this value may result in greater memory usage. +{{% /notice %}} +type | Integer +default | `100` +environment variable | `SENSU_BACKEND_PIPELINED_BUFFER_SIZE` +command line example | {{< code shell >}} +sensu-backend start --pipelined-buffer-size 100{{< /code >}} +backend.yml config file example | {{< code shell >}} +pipelined-buffer-size: 100{{< /code >}} + +| pipelined-workers | | +-----------------------|------ +description | Number of workers spawned for handling events through the event pipeline that are stored in the pipelined buffer. {{% notice warning %}} +**WARNING**: Modify with caution. Increasing this value may result in greater CPU usage. +{{% /notice %}} +type | Integer +default | `100` +environment variable | `SENSU_BACKEND_PIPELINED_WORKERS` +command line example | {{< code shell >}} +sensu-backend start --pipelined-workers 100{{< /code >}} +backend.yml config file example | {{< code shell >}} +pipelined-workers: 100{{< /code >}} + +## Backend configuration methods + +### Backend configuration file + +You can customize the backend configuration in a `.yml` configuration file. +The default backend configuration file path for Linux is `/etc/sensu/backend.yml`. + +To use the `backend.yml` file to configure the backend, list the desired configuration attributes and values. +Review the [example Sensu backend configuration file][17] for a complete example. + +{{% notice note %}} +**NOTE**: The backend loads configuration upon startup. +If you make changes in the `backend.yml` configuration file after startup, you must restart the backend for the changes to take effect. +{{% /notice %}} + +Configuration via command line flags or environment variables overrides any configuration specified in the backend configuration file. +Read [Create overrides][74] to learn more. + +### Command line flags + +You can customize the backend configuration with `sensu-agent start` command line flags. + +To use command line flags, specify the desired configuration options and values along with the `sensu-backend start` command. +For example: + +{{< code shell >}} +sensu-backend start --deregistration-handler slack_deregister --log-level debug +{{< /code >}} + +Configuration via command line flags overrides attributes specified in a configuration file or with environment variables. +Read [Create overrides][74] to learn more. + +### Environment variables + +Instead of using a configuration file or command line flags, you can use environment variables to configure your Sensu backend. +Each backend configuration option has an associated environment variable. +You can also create your own environment variables, as long as you name them correctly and save them in the correct place. +Here's how. + +1. Create the files from which the `sensu-backend` service configured by our supported packages will read environment variables: + + {{< language-toggle >}} + +{{< code shell "Debian family" >}} +sudo touch /etc/default/sensu-backend +{{< /code >}} + +{{< code shell "RHEL family" >}} +sudo touch /etc/sysconfig/sensu-backend +{{< /code >}} + + {{< /language-toggle >}} + +2. Make sure the environment variable is named correctly. + + * To rename a [configuration option][77] you wish to specify as an environment variable, prepend `SENSU_BACKEND_`, convert dashes to underscores, and capitalize all letters. + For example, the environment variable for the configuration option `api-listen-address` is `SENSU_BACKEND_API_LISTEN_ADDRESS`. + + * For a custom environment variable, you do not have to prepend `SENSU_BACKEND`. + For example, `TEST_VAR_1` is a valid custom environment variable name. + +3. Add the environment variable to the environment file. + + For example, to create `api-listen-address` as an environment variable and set it to `192.168.100.20:8080`: + + {{< language-toggle >}} + +{{< code shell "Debian family" >}} +echo 'SENSU_BACKEND_API_LISTEN_ADDRESS=192.168.100.20:8080' | sudo tee -a /etc/default/sensu-backend +{{< /code >}} + +{{< code shell "RHEL family" >}} +echo 'SENSU_BACKEND_API_LISTEN_ADDRESS=192.168.100.20:8080' | sudo tee -a /etc/sysconfig/sensu-backend +{{< /code >}} + + {{< /language-toggle >}} + +4. Restart the sensu-backend service so these settings can take effect: + + {{< language-toggle >}} + +{{< code shell "Debian family" >}} +sudo systemctl restart sensu-backend +{{< /code >}} + +{{< code shell "RHEL family" >}} +sudo systemctl restart sensu-backend +{{< /code >}} + + {{< /language-toggle >}} + +{{% notice note %}} +**NOTE**: Sensu includes an environment variable for each backend configuration option. +They are listed in the [configuration description tables](#general-configuration). +{{% /notice %}} + +### Format for label and annotation environment variables + +To use labels and annotations as environment variables in your handler configurations, you must use a specific format when you create the label and annotation environment variables. + +For example, to create the labels `"region": "us-east-1"` and `"type": "website"` as an environment variable: + +{{< language-toggle >}} + +{{< code shell "Debian family" >}} +echo 'BACKEND_LABELS='{"region": "us-east-1", "type": "website"}'' | sudo tee -a /etc/default/sensu-backend +{{< /code >}} + +{{< code shell "RHEL family" >}} +echo 'BACKEND_LABELS='{"region": "us-east-1", "type": "website"}'' | sudo tee -a /etc/sysconfig/sensu-backend +{{< /code >}} + +{{< /language-toggle >}} + +To create the annotations `"maintainer": "Team A"` and `"webhook-url": "https://hooks.slack.com/services/T0000/B00000/XXXXX"` as an environment variable: + +{{< language-toggle >}} + +{{< code shell "Debian family" >}} +echo 'BACKEND_ANNOTATIONS='{"maintainer": "Team A", "webhook-url": "https://hooks.slack.com/services/T0000/B00000/XXXXX"}'' | sudo tee -a /etc/default/sensu-backend +{{< /code >}} + +{{< code shell "RHEL family" >}} +echo 'BACKEND_ANNOTATIONS='{"maintainer": "Team A", "webhook-url": "https://hooks.slack.com/services/T0000/B00000/XXXXX"}'' | sudo tee -a /etc/sysconfig/sensu-backend +{{< /code >}} + +{{< /language-toggle >}} + +### Use environment variables with the Sensu backend + +Any environment variables you create in `/etc/default/sensu-backend` (Debian family) or `/etc/sysconfig/sensu-backend` (RHEL family) will be available to handlers executed by the Sensu backend. + +For example, if you create a custom environment variable `TEST_VARIABLE` in your sensu-backend file, it will be available to use in your handler configurations as `$TEST_VARIABLE`. +The following handler will print the `TEST_VARIABLE` value set in your sensu-backend file in `/tmp/test.txt`: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Handler +api_version: core/v2 +metadata: + name: print_test_var +spec: + command: echo $TEST_VARIABLE >> ./tmp/test.txt + timeout: 0 + type: pipe +{{< /code >}} + +{{< code json >}} +{ + "type": "Handler", + "api_version": "core/v2", + "metadata": { + "name": "print_test_var" + }, + "spec": { + "command": "echo $TEST_VARIABLE >> ./tmp/test.txt", + "timeout": 0, + "type": "pipe" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +{{% notice note %}} +**NOTE**: We recommend using secrets with the `Env` provider to expose secrets from environment variables on your Sensu backend nodes rather than using environment variables directly in your handler commands. +Read the [secrets reference](https://docs.sensu.io/sensu-go/latest/operations/manage-secrets/secrets/) and [Use Env for secrets management](../../../operations/manage-secrets/secrets-management/#use-env-for-secrets-management) for details. +{{% /notice %}} + +## Create configuration overrides + +Sensu has default settings and limits for certain configuration attributes, like the default log level. +Depending on your environment and preferences, you may want to create overrides for these Sensu-specific defaults and limits. + +You can create configuration overrides in several ways: + +- Command line configuration flag arguments for `sensu-backend start`. +- Environment variables in `/etc/default/sensu-backend` (Debian family) or `/etc/sysconfig/sensu-backend` (RHEL family). +- Configuration settings in the backend.yml config file. + +{{% notice note %}} +**NOTE**: We do not recommend editing the systemd unit file to create overrides. +Future package upgrades can overwrite changes in the systemd unit file. +{{% /notice %}} + +Sensu applies the following precedence to override settings: + +1. Arguments passed to the Sensu backend via command line configuration flags. +2. Environment variables in `/etc/default/sensu-backend` (Debian family) or `/etc/sysconfig/sensu-backend` (RHEL family). +3. Configuration in the backend.yml config file. + +For example, if you create overrides using all three methods, the command line configuration flag values will take precedence over the values you specify in `/etc/default/sensu-backend` or `/etc/sysconfig/sensu-backend` or the backend.yml config file. + +### Example override: Log level + +The default [log level][60] for the Sensu backend is `warn`. +To override the default and automatically apply a different log level for the backend, add the `--log-level` command line configuration flag when you start the Sensu backend. +For example, to specify `debug` as the log level: + +{{< code shell >}} +sensu-backend start --log-level debug +{{< /code >}} + +To configure an environment variable for the desired backend log level: + +{{< language-toggle >}} + +{{< code shell "Debian family" >}} +echo 'SENSU_BACKEND_LOG_LEVEL=debug' | sudo tee -a /etc/default/sensu-backend +{{< /code >}} + +{{< code shell "RHEL family" >}} +echo 'SENSU_BACKEND_LOG_LEVEL=debug' | sudo tee -a /etc/sysconfig/sensu-backend +{{< /code >}} + +{{< /language-toggle >}} + +To configure the desired log level in the config file, add this line to backend.yml: + +{{< code shell >}} +log-level: debug +{{< /code >}} + +## Event logging + +If you wish, you can log all Sensu event data to a file in JSON format. +The Sensu event log file can be a reliable input source for your favorite data lake solution as well as a buffer for event data that you send to a database in case the database is unavailable. + +{{% notice note %}} +**NOTE**: Event logs do not include log messages produced by sensu-backend service. +To write Sensu service logs to flat files on disk, read [Log Sensu services with systemd](../../../operations/monitor-sensu/log-sensu-systemd/). +{{% /notice %}} + +Depending on the number and size of events, logging status and metrics events to a file can require intensive input/output (I/O) performance. +Make sure you have adequate I/O capacity before using the event logging function. + +{{% notice protip %}} +**PRO TIP**: [TCP stream handlers](../../observe-process/tcp-stream-handlers/), which send observability event data to TCP sockets for external services to consume, are also a reliable way to transmit status and metrics event data without writing events to a local file. +{{% /notice %}} + +Use these backend configuration options to customize event logging: + +| event-log-buffer-size | | +-----------------------|------ +description | Buffer size of the event logger. Corresponds to the maximum number of events kept in memory in case the log file is temporarily unavailable or more events have been received than can be written to the log file. +type | Integer +default | 100000 +environment variable | `SENSU_BACKEND_EVENT_LOG_BUFFER_SIZE` +command line example | {{< code shell >}} +sensu-backend start --event-log-buffer-size 100000{{< /code >}} +backend.yml config file example | {{< code shell >}} +event-log-buffer-size: 100000{{< /code >}} + +| event-log-buffer-wait | | +-----------------------|------ +description | Buffer wait time for the event logger. When the buffer is full, the event logger will wait for the specified time for the writer to consume events from the buffer. +type | String +default | 10ms +environment variable | `SENSU_BACKEND_EVENT_LOG_BUFFER_WAIT` +command line example | {{< code shell >}} +sensu-backend start --event-log-buffer-wait 10ms{{< /code >}} +backend.yml config file example | {{< code shell >}} +event-log-buffer-wait: 10ms{{< /code >}} + + + +| event-log-file | | +-----------------------|------ +description | Path to the event log file. {{% notice warning %}} +**WARNING**: The log file should be located on a local drive. Logging directly to network drives is not supported. +{{% /notice %}} +type | String +environment variable | `SENSU_BACKEND_EVENT_LOG_FILE` +command line example | {{< code shell >}} +sensu-backend start --event-log-file /var/log/sensu/events.log{{< /code >}} +backend.yml config file example | {{< code shell >}} +event-log-file: "/var/log/sensu/events.log"{{< /code >}} + + + +| event-log-parallel-encoders | | +-----------------------|------ +description | Indicates whether Sensu should use parallel JSON encoders for event logging. If `true`, Sensu sets the number of JSON encoder workers to 50% of the total number of cores, with a minimum of 2 (for example, 6 JSON encoders on a 12-core machine). Otherwise, Sensu uses the default setting, which is a single JSON encoding worker.

    The `event-log-parallel-encoders` setting will not take effect unless you also specify a path to the event log file with the [`event-log-file`][61] configuration attribute. +type | Boolean +default | false +environment variable | `SENSU_BACKEND_EVENT_LOG_PARALLEL_ENCODERS` +command line example | {{< code shell >}} +sensu-backend start --event-log-parallel-encoders true{{< /code >}} +backend.yml config file example | {{< code shell >}} +event-log-parallel-encoders: true{{< /code >}} + +### Log rotation + +To manually rotate event logs, first rename (move) the current log file. +Then, send the *SIGHUP* signal to the sensu-backend process so it creates a new log file and starts logging to it. +Most Linux distributions include `logrotate` to automatically rotate log files as a standard utility, configured to run once per day by default. + +Because event log files can grow quickly for larger Sensu installations, we recommend using `logrotate` to automatically rotate log files more frequently. +To use the example log rotation configurations listed below, you may need to [configure `logrotate` to run once per hour][29]. + +#### Log rotation for systemd + +In this example, the `postrotate` script will reload the backend after log rotate is complete. +{{< code shell >}} +/var/log/sensu/events.log +{ + rotate 3 + hourly + missingok + notifempty + compress + postrotate + /bin/systemctl reload sensu-backend.service > /dev/null 2>/dev/null || true + endscript +} +{{< /code >}} + +Without the `postrotate` script, the backend will not reload. +This will cause sensu-backend (and sensu-agent, if translated for the Sensu agent) to no longer write to the log file, even if logrotate recreates the log file. + +#### Log rotation for sysvinit + +{{< code shell >}} +/var/log/sensu/events.log +{ + rotate 3 + hourly + missingok + notifempty + compress + postrotate + kill -HUP `cat /var/run/sensu/sensu-backend.pid 2> /dev/null` 2> /dev/null || true + endscript +} +{{< /code >}} + +## Platform metrics logging + +Sensu automatically writes core platform metrics in [InfluxDB Line Protocol][62] to a file at `/var/log/sensu/backend-stats.log`. +You can use this file as an input source for your favorite data lake solution. + +Metrics logging is enabled by default but can be disabled with the `disable-platform-metrics` configuration option. +Sensu appends updated metrics at the interval you specify with the `platform-metrics-logging-interval` configuration option (default is every 60 seconds). + +To rotate the platform metrics log, use the same methods as for [event log rotation][63]. + +Use these backend configuration options to customize platform metrics logging: + +| disable-platform-metrics | | +-----------------------|------ +description | `true` to disable platform metrics logging. Otherwise, `false`. +type | Boolean +default | false +environment variable | `SENSU_BACKEND_DISABLE_PLATFORM_METRICS` +command line example | {{< code shell >}} +sensu-backend start --disable-platform-metrics false{{< /code >}} +backend.yml config file example | {{< code shell >}} +disable-platform-metrics: false{{< /code >}} + +| platform-metrics-log-file | | +-----------------------|------ +description | Path to the platform metrics log file.{{% notice warning %}} +**WARNING**: The log file should be located on a local drive. Logging directly to network drives is not supported. +{{% /notice %}} +type | String +default | /var/log/sensu/sensu-backend/stats.log +environment variable | `SENSU_BACKEND_PLATFORM_METRICS_LOG_FILE` +command line example | {{< code shell >}} +sensu-backend start --platform-metrics-log-file /var/log/sensu/sensu-backend/stats.log{{< /code >}} +backend.yml config file example | {{< code shell >}} +platform-metrics-log-file: "/var/log/sensu/sensu-backend/stats.log"{{< /code >}} + +| platform-metrics-logging-interval | | +-----------------------|------ +description | Interval at which Sensu should append metrics to the platform metrics log. +type | String +default | 60s +environment variable | `SENSU_BACKEND_PLATFORM_METRICS_LOGGING_INTERVAL` +command line example | {{< code shell >}} +sensu-backend start --platform-metrics-logging-interval 60s{{< /code >}} +backend.yml config file example | {{< code shell >}} +platform-metrics-logging-interval: 60s{{< /code >}} + +## Service management + +{{% notice note %}} +**NOTE**: Service management commands may require administrative privileges. +{{% /notice %}} + +### Start the service + +Use the `sensu-backend` tool to start the backend and apply configuration flags. + +Start the backend with [configuration flags][15]: + +{{< code shell >}} +sensu-backend start --state-dir /var/lib/sensu/sensu-backend --log-level debug +{{< /code >}} + +View available configuration flags and defaults: + +{{< code shell >}} +sensu-backend start --help +{{< /code >}} + +If you do not include any configuration flags with the `sensu-backend start` command, the backend loads configuration from `/etc/sensu/backend.yml` by default. + +Start the backend using a service manager: + +{{< code shell >}} +sudo systemctl start sensu-backend +{{< /code >}} + +### Stop the service + +Stop the backend service using a service manager: + +{{< code shell >}} +sudo systemctl stop sensu-backend +{{< /code >}} + +### Restart the service + +Restart the backend using a service manager: + +{{< code shell >}} +sudo systemctl restart sensu-backend +{{< /code >}} + +You must restart the backend to implement any configuration updates. + +### Enable on boot + +Enable the backend to start on system boot: + +{{< code shell >}} +sudo systemctl enable sensu-backend +{{< /code >}} + +Disable the backend from starting on system boot: + +{{< code shell >}} +sudo systemctl disable sensu-backend +{{< /code >}} + +{{% notice note %}} +**NOTE**: On older distributions of Linux, use `sudo chkconfig sensu-server on` to enable the backend and `sudo chkconfig sensu-server off` to disable the backend. +{{% /notice %}} + +### Get service status + +View the status of the backend service using a service manager: + +{{< code shell >}} +sudo systemctl status sensu-backend +{{< /code >}} + +### Get service version + +Get the current backend version using the `sensu-backend` tool: + +{{< code shell >}} +sensu-backend version +{{< /code >}} + +### Get help + +The `sensu-backend` tool provides general and command-specific help flags. + +View sensu-backend commands: + +{{< code shell >}} +sensu-backend help +{{< /code >}} + +List options for a specific command (in this case, sensu-backend start): + +{{< code shell >}} +sensu-backend start --help +{{< /code >}} + + +[1]: ../../../operations/deploy-sensu/install-sensu#install-the-sensu-backend +[2]: https://etcd.io/docs +[3]: ../monitor-server-resources/ +[4]: ../collect-metrics-with-checks/ +[5]: ../checks/ +[6]: ../../../web-ui/ +[7]: ../../observe-process/send-slack-alerts/ +[8]: ../../observe-filter/reduce-alert-fatigue/ +[9]: ../../observe-filter/filters/ +[10]: ../../observe-transform/mutators/ +[11]: ../../observe-process/handlers/ +[12]: #datastore-and-cluster-configuration +[13]: ../../../operations/deploy-sensu/cluster-sensu/ +[14]: ../../../api/ +[15]: #general-configuration +[16]: https://etcd.io/docs/current/tuning/#time-parameters +[17]: ../../../files/backend.yml +[18]: https://golang.org/pkg/crypto/tls/#pkg-constants +[19]: https://etcd.io/docs/latest/op-guide/clustering/#discovery +[20]: https://etcd.io/docs/latest/op-guide/clustering/#etcd-discovery +[21]: https://etcd.io/docs/latest/op-guide/clustering/#dns-discovery +[22]: #initialization +[23]: #etcd-listen-client-urls +[24]: ../../../operations/deploy-sensu/install-sensu#2-configure-and-start +[25]: ../../../operations/deploy-sensu/install-sensu#3-initialize +[26]: ../../../sensuctl/#change-the-admin-users-password +[27]: https://golang.org/pkg/net/http/pprof/ +[28]: ../subscriptions/ +[29]: https://unix.stackexchange.com/questions/29574/how-can-i-set-up-logrotate-to-rotate-logs-hourly +[30]: https://en.m.wikipedia.org/wiki/WebSocket +[31]: ../../../operations/deploy-sensu/secure-sensu/#optional-configure-sensu-agent-mtls-authentication +[32]: ../../../operations/deploy-sensu/generate-certificates/ +[33]: ../../../operations/deploy-sensu/secure-sensu/ +[34]: ../agent/#username-and-password-authentication +[35]: ../../../operations/deploy-sensu/install-sensu/#architecture-overview +[36]: #etcd-heartbeat-interval +[37]: ../../../sensuctl/ +[38]: #configuration-via-environment-variables +[39]: ../../../operations/control-access/use-apikeys/ +[60]: #backend-log-level +[61]: #event-log-file +[62]: https://docs.influxdata.com/enterprise_influxdb/v1.9/write_protocols/line_protocol_reference/ +[63]: #log-rotation +[64]: ../../../sensuctl/#use-global-flags-for-sensuctl-settings +[65]: #event-logging +[66]: #platform-metrics-logging +[67]: #agent-rate-limit +[68]: ../../../operations/control-access/namespaces/#default-namespaces +[69]: ../../observe-entities/entities/#backend-entities +[70]: ../../observe-process/pipelines/ +[71]: ../../../guides/ +[72]: #datastore-and-cluster-configuration +[73]: #advanced-configuration-options +[74]: #create-configuration-overrides +[75]: #state-dir-option +[76]: #backend-configuration-file +[77]: #backend-configuration-options +[78]: #environment-variables +[79]: #backend-configuration-methods +[80]: ../../../operations/deploy-sensu/secure-sensu/#certificate-revocation-check +[81]: ../../observe-process/silencing/#silence-expireat +[82]: ../../observe-process/silencing/ + diff --git a/content/sensu-go/6.12/observability-pipeline/observe-schedule/business-service-monitoring-sdk.md b/content/sensu-go/6.12/observability-pipeline/observe-schedule/business-service-monitoring-sdk.md new file mode 100644 index 0000000000..c8843825e6 --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-schedule/business-service-monitoring-sdk.md @@ -0,0 +1,134 @@ +--- +title: "Business service monitoring SDK" +linkTitle: "Business Service Monitoring SDK" +description: "Use Sensu's business service monitoring SDK of JavaScript-based expressions to add functionality for Sensu rule templates that evaluate service components." +weight: 130 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: observe-schedule +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access business service monitoring (BSM) in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} + +{{% notice note %}} +**NOTE**: Business service monitoring (BSM) is in public preview and is subject to change. +{{% /notice %}} + +Sensu's business service monitoring (BSM) feature uses a dedicated SDK of JavaScript-based expressions that provide additional functionality. +Use the BSM SDK to create custom JavaScript expressions with complex logic. + +BSM SDK expressions are defined in [rule templates][3], so they act in the context of determining whether aggregate data derived from a service component’s selection of Sensu Go events should trigger a rule-based event. +They always receive a single event and some information about that event, like `event.timestamp` or `event.check.interval`, and always return either `true` or `false`. + +BSM SDK expressions are evaluated by the [Otto JavaScript VM][1] as JavaScript programs. + +{{% notice note %}} +**NOTE**: [Sensu query expressions](../../observe-filter/sensu-query-expressions/) also provide JavaScript functions for using nested parameters and custom functions to retrieve events from the event store. +{{% /notice %}} + +## Syntax quick reference + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    operatordescription
    ===Identity
    !==Nonidentity
    ==Equality
    !=Inequality
    &&Logical AND
    ||Logical OR
    <Less than
    >Greater than
    <=Less than or equal to
    >=Greater than or equal to
    + +## Specification + +BSM SDK expressions are valid ECMAScript 5 (JavaScript) expressions that return either `true` or `false`. +Other values are not allowed. +If an expression returns a value besides `true` or `false`, the [Sensu backend log][2] will record an error and the filter will evaluate to `false`. + +The BSM SDK allows you to to express rules for the number or percentage of events with critical, warning, OK, and unknown statuses. +You can also configure expressions to ignore silenced events. + +## Custom functions + +The Sensu BSM SDK includes two custom functions: `sensu.Count()` and `sensu.Percentage()`. + +### sensu.Count() + +The custom function `sensu.Count()` returns the number of events with the specified status. +For example, to return the number of events with `ok` status: + +{{< code go >}} +sensu.Count("ok") +{{< /code >}} + +### sensu.Percentage() + +The custom function `sensu.Percentage()` returns the percentage of events with the specified status. +For example, to return the percentage of events with `critical` status: + +{{< code go >}} +sensu.Percentage("critical") +{{< /code >}} + +## Example BSM SDK expression + +The following BSM SDK expression creates a critical event if at least 35% of events generated by the service component have `critical` status **or** creates a warning event if the service component generates one or more events with `warning` status: + +{{< code go >}} +if (sensu.Percentage("critical") >= 35) { + event.check = {status: 2, output: "critical event"} +} else if (sensu.Count("warning") >= 1) { + event.check = {status: 1, output: "warning event"} +} +{{< /code >}} + + +[1]: https://github.com/robertkrimen/otto +[2]: ../backend/#event-logging +[3]: ../rule-templates/ diff --git a/content/sensu-go/6.12/observability-pipeline/observe-schedule/business-service-monitoring.md b/content/sensu-go/6.12/observability-pipeline/observe-schedule/business-service-monitoring.md new file mode 100644 index 0000000000..fa16b88256 --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-schedule/business-service-monitoring.md @@ -0,0 +1,417 @@ +--- +title: "Monitor Business Services" +guide_title: "Monitor business services" +type: "guide" +description: "Use Sensu's business service monitoring (BSM) to monitor every component in your system with a top-down approach that produces meaningful information." +product: "Sensu Go" +version: "6.12" +weight: 200 +layout: "single" +toc: true +menu: + sensu-go-6.12: + parent: observe-schedule +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access business service monitoring (BSM) in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} + +{{% notice note %}} +**NOTE**: Business service monitoring (BSM) is in public preview and is subject to change. +{{% /notice %}} + +Sensu's business service monitoring (BSM) provides high-level visibility into the current health of any number of your business services. +Use BSM to monitor every component in your system with a top-down approach that produces meaningful alerts, prevents alert fatigue, and helps you focus on your core business services. + +BSM requires two resources that work together to achieve top-down monitoring: [service components][1] and [rule templates][2]. +Service components are the elements that make up your business services. +Rule templates define the monitoring rules that produce events for service components based on customized evaluation expressions. + +An example of a business service might be a company website. +The website itself might have three service components: the primary webserver that publishes website pages, a backup webserver in case the primary webserver fails, and an inventory database for the shop section of the website. +At least one webserver and the database must be in an OK state for the website to be fully available. + +In this scenario, you could use BSM to create a current status page for this company website that displays the website's high-level status at a glance. +As long as one webserver and the database have an OK status, the website status is OK. +Otherwise, the website status is not OK. +Most people probably just want to know whether the website is currently available — it won't matter to them whether the website is functioning with one or both webservers. + +At the same time, the company *does* want to make sure the right person addresses any webserver failures, even if the website is technically still OK. +BSM allows you to customize rule templates that apply a threshold for taking action for different service components as well as what action to take. + +To continue the company website example, if the primary webserver fails but the backup webserver does not, you might use a rule template that creates a service ticket to address the next workday (in addition to the rule template that is emitting "OK" events for the current status page). +Another monitoring rule might trigger an alert to the on-call operator should both webservers or the inventory database fail. + +{{% notice note %}} +**NOTE**: BSM requires high event throughput. +Configure a [PostgreSQL datastore](../../../operations/deploy-sensu/scale-event-storage/) to achieve the required throughput and use the BSM feature. +{{% /notice %}} + +## Service component example + +Here is an example service component definition that includes the `website-services` service and applies the built-in [`aggregate` rule template][6] for events generated by checks with the `webserver` subscription: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: ServiceComponent +api_version: bsm/v1 +metadata: + name: webservers +spec: + services: + - website-services + interval: 60 + query: + - type: fieldSelector + value: webserver in event.check.subscriptions + rules: + - template: aggregate + name: webservers_50-70 + arguments: + critical_threshold: 70 + warning_threshold: 50 + handlers: + - slack +{{< /code >}} + +{{< code json >}} +{ + "type": "ServiceComponent", + "api_version": "bsm/v1", + "metadata": { + "name": "webservers" + }, + "spec": { + "services": [ + "website-services" + ], + "interval": 60, + "query": [ + { + "type": "fieldSelector", + "value": "webserver in event.check.subscriptions" + } + ], + "rules": [ + { + "template": "aggregate", + "name": "webservers_50-70", + "arguments": { + "critical_threshold": 70, + "warning_threshold": 50 + } + } + ], + "handlers": [ + "slack" + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Rule template example + +This example lists the definition for the built-in [aggregate][6] rule template: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: RuleTemplate +api_version: bsm/v1 +metadata: + name: aggregate + namespace: default +spec: + arguments: + properties: + critical_count: + description: create an event with a critical status if there the number of + critical events is equal to or greater than this count + type: number + critical_threshold: + description: create an event with a critical status if the percentage of non-zero + events is equal to or greater than this threshold + type: number + metric_handlers: + default: {} + description: metric handlers to use for produced metrics + items: + type: string + type: array + produce_metrics: + default: {} + description: produce metrics from aggregate data and include them in the produced + event + type: boolean + set_metric_annotations: + default: {} + description: annotate the produced event with metric annotations + type: boolean + warning_count: + description: create an event with a warning status if there the number of + critical events is equal to or greater than this count + type: number + warning_threshold: + description: create an event with a warning status if the percentage of non-zero + events is equal to or greater than this threshold + type: number + required: + description: Monitor a distributed service - aggregate one or more events into a + single event. This BSM rule template allows you to treat the results of multiple + disparate check executions – executed across multiple disparate systems – as a + single event. This template is extremely useful in dynamic environments and/or + environments that have a reasonable tolerance for failure. Use this template when + a service can be considered healthy as long as a minimum threshold is satisfied + (e.g. at least 5 healthy web servers? at least 70% of N processes healthy?). + eval: |2 + if (events && events.length == 0) { + event.check.output = "WARNING: No events selected for aggregate + "; + event.check.status = 1; + return event; + } + event.annotations["io.sensu.bsm.selected_event_count"] = events.length; + percentOK = sensu.PercentageBySeverity("ok"); + if (!!args["produce_metrics"]) { + var ts = Math.floor(new Date().getTime() / 1000); + event.timestamp = ts; + var tags = [ + { + name: "service", + value: event.entity.name + }, + { + name: "entity", + value: event.entity.name + }, + { + name: "check", + value: event.check.name + } + ]; + event.metrics = sensu.NewMetrics({ + points: [ + { + name: "percent_non_zero", + timestamp: ts, + value: sensu.PercentageBySeverity("non-zero"), + tags: tags + }, + { + name: "percent_ok", + timestamp: ts, + value: percentOK, + tags: tags + }, + { + name: "percent_warning", + timestamp: ts, + value: sensu.PercentageBySeverity("warning"), + tags: tags + }, + { + name: "percent_critical", + timestamp: ts, + value: sensu.PercentageBySeverity("critical"), + tags: tags + }, + { + name: "percent_unknown", + timestamp: ts, + value: sensu.PercentageBySeverity("unknown"), + tags: tags + }, + { + name: "count_non_zero", + timestamp: ts, + value: sensu.CountBySeverity("non-zero"), + tags: tags + }, + { + name: "count_ok", + timestamp: ts, + value: sensu.CountBySeverity("ok"), + tags: tags + }, + { + name: "count_warning", + timestamp: ts, + value: sensu.CountBySeverity("warning"), + tags: tags + }, + { + name: "count_critical", + timestamp: ts, + value: sensu.CountBySeverity("critical"), + tags: tags + }, + { + name: "count_unknown", + timestamp: ts, + value: sensu.CountBySeverity("unknown"), + tags: tags + } + ] + }); + if (!!args["metric_handlers"]) { + event.metrics.handlers = args["metric_handlers"].slice(); + } + if (!!args["set_metric_annotations"]) { + var i = 0; + while(i \u003c event.metrics.points.length) { + event.annotations["io.sensu.bsm.selected_event_" + event.metrics.points[i].name] = event.metrics.points[i].value.toString(); + i++; + } + } + } + if (!!args["critical_threshold"] && percentOK \u003c= args["critical_threshold"]) { + event.check.output = "CRITICAL: Less than " + args["critical_threshold"].toString() + "% of selected events are OK (" + percentOK.toString() + "%) + "; + event.check.status = 2; + return event; + } + if (!!args["warning_threshold"] && percentOK \u003c= args["warning_threshold"]) { + event.check.output = "WARNING: Less than " + args["warning_threshold"].toString() + "% of selected events are OK (" + percentOK.toString() + "%) + "; + event.check.status = 1; + return event; + } + if (!!args["critical_count"]) { + crit = sensu.CountBySeverity("critical"); + if (crit \u003e= args["critical_count"]) { + event.check.output = "CRITICAL: " + args["critical_count"].toString() + " or more selected events are in a critical state (" + crit.toString() + ") + "; + event.check.status = 2; + return event; + } + } + if (!!args["warning_count"]) { + warn = sensu.CountBySeverity("warning"); + if (warn \u003e= args["warning_count"]) { + event.check.output = "WARNING: " + args["warning_count"].toString() + " or more selected events are in a warning state (" + warn.toString() + ") + "; + event.check.status = 1; + return event; + } + } + event.check.output = "Everything looks good (" + percentOK.toString() + "% OK)"; + event.check.status = 0; + return event; +{{< /code >}} + +{{< code json >}} +{ + "type": "RuleTemplate", + "api_version": "bsm/v1", + "metadata": { + "name": "aggregate", + "namespace": "default" + }, + "spec": { + "arguments": { + "properties": { + "critical_count": { + "description": "create an event with a critical status if there the number of critical events is equal to or greater than this count", + "type": "number" + }, + "critical_threshold": { + "description": "create an event with a critical status if the percentage of non-zero events is equal to or greater than this threshold", + "type": "number" + }, + "metric_handlers": { + "default": {}, + "description": "metric handlers to use for produced metrics", + "items": { + "type": "string" + }, + "type": "array" + }, + "produce_metrics": { + "default": {}, + "description": "produce metrics from aggregate data and include them in the produced event", + "type": "boolean" + }, + "set_metric_annotations": { + "default": {}, + "description": "annotate the produced event with metric annotations", + "type": "boolean" + }, + "warning_count": { + "description": "create an event with a warning status if there the number of critical events is equal to or greater than this count", + "type": "number" + }, + "warning_threshold": { + "description": "create an event with a warning status if the percentage of non-zero events is equal to or greater than this threshold", + "type": "number" + } + }, + "required": null + }, + "description": "Monitor a distributed service - aggregate one or more events into a single event. This BSM rule template allows you to treat the results of multiple disparate check executions – executed across multiple disparate systems – as a single event. This template is extremely useful in dynamic environments and/or environments that have a reasonable tolerance for failure. Use this template when a service can be considered healthy as long as a minimum threshold is satisfied (e.g. at least 5 healthy web servers? at least 70% of N processes healthy?).", + "eval": "\nif (events \\u0026\\u0026 events.length == 0) {\n event.check.output = \"WARNING: No events selected for aggregate\n\";\n event.check.status = 1;\n return event;\n}\n\nevent.annotations[\"io.sensu.bsm.selected_event_count\"] = events.length;\n\npercentOK = sensu.PercentageBySeverity(\"ok\");\n\nif (!!args[\"produce_metrics\"]) {\n var ts = Math.floor(new Date().getTime() / 1000);\n\n event.timestamp = ts;\n\n var tags = [\n {\n name: \"service\",\n value: event.entity.name\n },\n {\n name: \"entity\",\n value: event.entity.name\n },\n {\n name: \"check\",\n value: event.check.name\n }\n ];\n\n event.metrics = sensu.NewMetrics({\n points: [\n {\n name: \"percent_non_zero\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"non-zero\"),\n tags: tags\n },\n {\n name: \"percent_ok\",\n timestamp: ts,\n value: percentOK,\n tags: tags\n },\n {\n name: \"percent_warning\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"warning\"),\n tags: tags\n },\n {\n name: \"percent_critical\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"critical\"),\n tags: tags\n },\n {\n name: \"percent_unknown\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"unknown\"),\n tags: tags\n },\n {\n name: \"count_non_zero\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"non-zero\"),\n tags: tags\n },\n {\n name: \"count_ok\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"ok\"),\n tags: tags\n },\n {\n name: \"count_warning\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"warning\"),\n tags: tags\n },\n {\n name: \"count_critical\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"critical\"),\n tags: tags\n },\n {\n name: \"count_unknown\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"unknown\"),\n tags: tags\n }\n ]\n });\n\n if (!!args[\"metric_handlers\"]) {\n event.metrics.handlers = args[\"metric_handlers\"].slice();\n }\n\n if (!!args[\"set_metric_annotations\"]) {\n var i = 0;\n\n while(i \\u003c event.metrics.points.length) {\n event.annotations[\"io.sensu.bsm.selected_event_\" + event.metrics.points[i].name] = event.metrics.points[i].value.toString();\n i++;\n }\n }\n}\n\nif (!!args[\"critical_threshold\"] \\u0026\\u0026 percentOK \\u003c= args[\"critical_threshold\"]) {\n event.check.output = \"CRITICAL: Less than \" + args[\"critical_threshold\"].toString() + \"% of selected events are OK (\" + percentOK.toString() + \"%)\n\";\n event.check.status = 2;\n return event;\n}\n\nif (!!args[\"warning_threshold\"] \\u0026\\u0026 percentOK \\u003c= args[\"warning_threshold\"]) {\n event.check.output = \"WARNING: Less than \" + args[\"warning_threshold\"].toString() + \"% of selected events are OK (\" + percentOK.toString() + \"%)\n\";\n event.check.status = 1;\n return event;\n}\n\nif (!!args[\"critical_count\"]) {\n crit = sensu.CountBySeverity(\"critical\");\n\n if (crit \\u003e= args[\"critical_count\"]) {\n event.check.output = \"CRITICAL: \" + args[\"critical_count\"].toString() + \" or more selected events are in a critical state (\" + crit.toString() + \")\n\";\n event.check.status = 2;\n return event;\n }\n}\n\nif (!!args[\"warning_count\"]) {\n warn = sensu.CountBySeverity(\"warning\");\n\n if (warn \\u003e= args[\"warning_count\"]) {\n event.check.output = \"WARNING: \" + args[\"warning_count\"].toString() + \" or more selected events are in a warning state (\" + warn.toString() + \")\n\";\n event.check.status = 1;\n return event;\n }\n}\n\nevent.check.output = \"Everything looks good (\" + percentOK.toString() + \"% OK)\";\nevent.check.status = 0;\n\nreturn event;\n" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Configure BSM via the web UI + +The Sensu [web UI BSM module][3] allows you to create, edit, and delete service components and rule templates inside the web UI. + +## Configure BSM via APIs and sensuctl + +BSM service components and rule templates are Sensu resources with complete definitions, so you can use Sensu's [service component][1] and [rule template][2] APIs to create, retrieve, update, and delete service components and rule templates. + +You can also use [sensuctl][5] to create and manage service components and rule templates via the APIs from the command line. + +## Disable BSM + +Some users may want to disable BSM in the UI, this can be accomplished via [GlobalConfig][7]: + + +{{< language-toggle >}} + +{{< code shell "YML" >}} +cat << EOF | sensuctl create +--- +type: GlobalConfig +api_version: web/v1 +metadata: + name: default +spec: + disable_bsm: true +EOF +{{< /code >}} + +{{< code shell "JSON" >}} +cat << EOF | sensuctl create +{ + "type": "GlobalConfig", + "api_version": "web/v1", + "metadata": { + "name": "default" + }, + "spec": { + "disable_bsm": true + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + +[1]: ../service-components/ +[2]: ../rule-templates/ +[3]: ../../../web-ui/bsm-module/ +[4]: #service-component-example +[5]: ../../../sensuctl/ +[6]: ../rule-templates/#built-in-rule-template-aggregate +[7]: ../../../catalog/build-private-catalog/#create-a-ui-globalconfig-definition diff --git a/content/sensu-go/6.12/observability-pipeline/observe-schedule/checks.md b/content/sensu-go/6.12/observability-pipeline/observe-schedule/checks.md new file mode 100644 index 0000000000..b549ee0565 --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-schedule/checks.md @@ -0,0 +1,2593 @@ +--- +title: "Checks reference" +linkTitle: "Checks Reference" +reference_title: "Checks" +type: "reference" +description: "Read this reference to learn how Sensu checks and agents work to monitor your infrastructure automatically and send observability data to the Sensu backend." +weight: 30 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: observe-schedule +--- + +Checks work with Sensu agents to produce observability events automatically. +You can use checks to monitor server resources, services, and application health as well as collect and analyze metrics. +Read [Monitor server resources][12] to get started. +Use [Bonsai][29], the Sensu asset hub, to discover, download, and share Sensu check dynamic runtime assets. + +## Check example (minimum recommended attributes) + +This example shows a check resource definition that includes the minimum recommended attributes. + +{{% notice note %}} +**NOTE**: The attribute `interval` is not required if a valid `cron` schedule is defined. +Read [scheduling](#interval-scheduling) for more information. +{{% /notice %}} + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: check_minimum +spec: + command: collect.sh + handlers: + - slack + interval: 10 + publish: true + subscriptions: + - system +{{< /code >}} + +{{< code json >}} +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "check_minimum" + }, + "spec": { + "command": "collect.sh", + "subscriptions": [ + "system" + ], + "handlers": [ + "slack" + ], + "interval": 10, + "publish": true + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Check commands + +Each Sensu check definition specifies a command and the schedule at which it should be executed. +Check commands are executable commands that the Sensu agent executes. + +A command may include command line arguments for controlling the behavior of the command executable. +Many common checks are available as dynamic runtime assets from [Bonsai][29] and support command line arguments so different check definitions can use the same executable. + +{{% notice note %}} +**NOTE**: Sensu advises against requiring root privileges to execute check commands or scripts. +The Sensu user is not permitted to kill timed-out processes invoked by the root user, which could result in zombie processes. +{{% /notice %}} + +### Check command execution + +All check commands are executed by Sensu agents as the `sensu` user. +Commands must be executable files that are discoverable on the Sensu agent system (for example, installed in a system `$PATH` directory). + +## Check result specification + +Although Sensu agents attempt to execute any command defined for a check, successful check result processing requires adherence to a simple specification. + +- Result data is output to [stdout or stderr][3]. + - For service checks, this output is typically a human-readable message. + - For metric checks, this output contains the measurements gathered by the + check. +- Exit status code indicates state. + - `0` indicates OK. + - `1` indicates WARNING. + - `2` indicates CRITICAL. + - Exit status codes other than `0`, `1`, and `2` indicate an UNKNOWN or custom status + +{{% notice protip %}} +**PRO TIP**: If you're familiar with the **Nagios** monitoring system, you may recognize this specification — it is the same one that Nagios plugins use. +As a result, you can use Nagios plugins with Sensu without any modification. +{{% /notice %}} + +At every execution of a check command, regardless of success or failure, the Sensu agent publishes the check’s result for eventual handling by the **event processor** (the Sensu backend). + +## Check scheduling + +The Sensu backend schedules checks and publishes check execution requests to entities via a [publish/subscribe model][2]. +Checks have a defined set of [subscriptions][64]: transport topics to which the Sensu backend publishes check requests. +Sensu entities become subscribers to these topics (called subscriptions) via their individual `subscriptions` attribute. + +You can schedule checks using the [`interval`][38], [`cron`][45], and [`publish`][63] attributes. +Sensu requires that checks include either an `interval` attribute (interval scheduling) or a `cron` attribute (cron scheduling). + +### Round robin checks + +By default, Sensu schedules checks once per interval for each agent with a matching subscription: one check execution per agent per interval. +Sensu also supports deduplicated check execution when configured with the `round_robin` check attribute. +For checks with `round_robin` set to `true`, Sensu executes the check once per interval, cycling through the available agents alphabetically according to agent name. + +For example, for three agents configured with the `system` subscription (agents A, B, and C), a check configured with the `system` subscription and `round_robin` set to `true` results in one observability event per interval, with the agent creating the event following the pattern A -> B -> C -> A -> B -> C for the first six intervals. + +{{< figure src="/images/go/checks_reference/round_robin_diagram.png" alt="Round robin check diagram" link="/images/go/checks_reference/round_robin_diagram.png" target="_blank" >}} + + +In the diagram above, the standard check is executed by agents A, B, and C every 60 seconds. +The round robin check cycles through the available agents, resulting in each agent executing the check every 180 seconds. + +To use check [`ttl`][31] and `round_robin` together, your check configuration must also specify a [`proxy_entity_name`][32]. +If you do not specify a `proxy_entity_name` when using check `ttl` and `round_robin` together, your check will stop executing. + +{{% notice protip %}} +**PRO TIP**: Use round robin to distribute check execution workload across multiple agents when using [proxy checks](#proxy-checks). +{{% /notice %}} + +#### Event storage for round robin scheduling + +If you use round robin scheduling for check execution, we recommend using [PostgreSQL][65] rather than etcd for event storage. +Etcd leases are unreliable as the scheduling mechanism for round robin check execution, and etcd will not produce precise round robin behavior. + +When you [enable round robin scheduling on PostgreSQL][66], any existing round robin scheduling will stop and migrate to PostgreSQL as entities check in with keepalives. +Sensu will gradually delete the existing etcd scheduler state as keepalives on the etcd scheduler keys expire over time. + +### Interval scheduling + +You can schedule a check to be executed at regular intervals using the `interval` and `publish` check attributes. +For example, to schedule a check to execute every 60 seconds, set the `interval` attribute to `60` and the `publish` attribute to `true`. + +{{% notice note %}} +**NOTE**: When creating an interval check, Sensu calculates an initial offset to splay the check's first scheduled request. +This helps balance the load of both the backend and the agent and may result in a delay before initial check execution. +{{% /notice %}} + +#### Example interval check + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: interval_check +spec: + command: check-cpu.sh -w 75 -c 90 + handlers: + - slack + interval: 60 + publish: true + subscriptions: + - system +{{< /code >}} + +{{< code json >}} +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "interval_check" + }, + "spec": { + "command": "check-cpu.sh -w 75 -c 90", + "subscriptions": ["system"], + "handlers": ["slack"], + "interval": 60, + "publish": true + } +} +{{< /code >}} + +{{< /language-toggle >}} + +### Cron scheduling + +You can also schedule checks using [cron syntax][14]. + +Examples of valid cron values include: + +- `cron: CRON_TZ=Asia/Tokyo * * * * *` +- `cron: TZ=Asia/Tokyo * * * * *` +- `cron: '* * * * *'` + +{{% notice note %}} +**NOTE**: If you're using YAML to create a check that uses cron scheduling and the first character of the cron schedule is an asterisk (`*`), place the entire cron schedule inside single or double quotes (for example, `cron: '* * * * *'`). +{{% /notice %}} + +#### Example cron checks + +To schedule a check to execute once a minute at the start of the minute, set the `cron` attribute to `* * * * *` and the `publish` attribute to `true`: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: cron_check +spec: + command: check-cpu.sh -w 75 -c 90 + cron: '* * * * *' + handlers: + - slack + publish: true + subscriptions: + - system +{{< /code >}} + +{{< code json >}} +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "cron_check" + }, + "spec": { + "command": "check-cpu.sh -w 75 -c 90", + "subscriptions": ["system"], + "handlers": ["slack"], + "cron": "* * * * *", + "publish": true + } +} +{{< /code >}} + +{{< /language-toggle >}} + +Use a prefix of `TZ=` or `CRON_TZ=` to set a [timezone][30] for the `cron` attribute: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: cron_check +spec: + check_hooks: null + command: hi + cron: CRON_TZ=Asia/Tokyo * * * * * + env_vars: null + handlers: [] + high_flap_threshold: 0 + interval: 0 + low_flap_threshold: 0 + output_metric_format: "" + output_metric_handlers: null + output_metric_tags: null + proxy_entity_name: "" + publish: true + round_robin: false + runtime_assets: null + stdin: false + subdue: null + subscriptions: + - sys + timeout: 0 + ttl: 0 +{{< /code >}} + +{{< code json >}} +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "cron_check" + }, + "spec": { + "check_hooks": null, + "command": "hi", + "cron": "CRON_TZ=Asia/Tokyo * * * * *", + "env_vars": null, + "handlers": [], + "high_flap_threshold": 0, + "interval": 0, + "low_flap_threshold": 0, + "output_metric_format": "", + "output_metric_handlers": null, + "output_metric_tags": null, + "proxy_entity_name": "", + "publish": true, + "round_robin": false, + "runtime_assets": null, + "stdin": false, + "subdue": null, + "subscriptions": [ + "sys" + ], + "timeout": 0, + "ttl": 0 + } +} +{{< /code >}} + +{{< /language-toggle >}} + +### Ad hoc scheduling + +In addition to automatic execution, you can create checks to be scheduled manually using [core/v2/checks API endpoints][34]. +To create a check with ad-hoc scheduling, set the `publish` attribute to `false` in addition to an `interval` or `cron` schedule. + +#### Example ad hoc check + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: ad_hoc_check +spec: + command: check-cpu.sh -w 75 -c 90 + handlers: + - slack + interval: 60 + publish: false + subscriptions: + - system +{{< /code >}} + +{{< code json >}} +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "ad_hoc_check" + }, + "spec": { + "command": "check-cpu.sh -w 75 -c 90", + "subscriptions": ["system"], + "handlers": ["slack"], + "interval": 60, + "publish": false + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Proxy checks + +Sensu supports running proxy checks that associate events with a entity that isn’t actually executing the check, regardless of whether that entity is an agent entity or a proxy entity. +Proxy entities allow Sensu to monitor external resources on systems and devices where a Sensu agent cannot be installed, like a network switch or a website. +You can create a proxy check using [`proxy_entity_name`][35] or [`proxy_requests`][36]. + +When you create a proxy check, make sure the check definition includes a subscription that matches the subscription of at least one agent entity to define which agents will run the check. +Proxy entities do not use subscriptions. + +To avoid duplicate events, use the [`round_robin` check attribute][43] with proxy checks. +Read [Round robin checks][52] and [Proxy entities and round robin scheduling][86] to learn more. + +Read [Monitor external resources with proxy entities][28] to learn how to create proxy checks to generate events for one or more proxy entities. + +### Use a proxy check to monitor a proxy entity + +When executing checks that include a `proxy_entity_name`, Sensu agents report the resulting events under the specified proxy entity instead of the agent entity. +If the proxy entity doesn't exist, Sensu creates the proxy entity when the backend receives the event. + +#### Example proxy check using `proxy_entity_name` + +The following proxy check runs every 60 seconds, cycling through the agents with the `run_proxies` subscription alphabetically according to the agent name, for the proxy entity `sensu-site`. + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: proxy_check +spec: + command: http_check.sh https://sensu.io + handlers: + - slack + interval: 60 + proxy_entity_name: sensu-site + publish: true + round_robin: true + subscriptions: + - run_proxies +{{< /code >}} + +{{< code json >}} +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "proxy_check" + }, + "spec": { + "command": "http_check.sh https://sensu.io", + "subscriptions": ["run_proxies"], + "handlers": ["slack"], + "interval": 60, + "publish": true, + "round_robin": true, + "proxy_entity_name": "sensu-site" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +### Use a proxy check to monitor multiple proxy entities + +The [`proxy_requests` check attributes][37] allow Sensu to run a check for each entity that matches the expressions specified in the `entity_attributes`, resulting in observability events that represent each matching proxy entity. +The entity attributes must match exactly as stated. + +No variables or directives have any special meaning, but you can use [Sensu query expressions][11] to perform more complicated filtering on the available value, such as finding entities with a particular class or label. + +Combine `proxy_requests` attributes with with [token substitution][39] as shown in the example proxy check below to monitor multiple entities using a single check definition. + +#### Example proxy check using `proxy_requests` + +The following proxy check runs every 60 seconds, cycling through the agents with the `run_proxies` subscription alphabetically according to the agent name, for all existing proxy entities with the custom label `proxy_type` set to `website`. + +This check uses [token substitution][39] to import the value of the custom entity label `url` to complete the check command. +Read the [entities reference][40] for information about adding custom labels to entities. + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: proxy_check_proxy_requests +spec: + command: http_check.sh {{ .labels.url }} + handlers: + - slack + interval: 60 + proxy_requests: + entity_attributes: + - entity.labels.proxy_type == 'website' + publish: true + round_robin: true + subscriptions: + - run_proxies +{{< /code >}} + +{{< code json >}} +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "proxy_check_proxy_requests" + }, + "spec": { + "command": "http_check.sh {{ .labels.url }}", + "subscriptions": ["run_proxies"], + "handlers": ["slack"], + "interval": 60, + "publish": true, + "proxy_requests": { + "entity_attributes": [ + "entity.labels.proxy_type == 'website'" + ] + }, + "round_robin": true + } +} +{{< /code >}} + +{{< /language-toggle >}} + +#### Fine-tune proxy check scheduling with splay + +Use the [`splay`][72] and [`splay_coverage`][73] attributes to distribute proxy check executions across the check interval. + +To continue the [example proxy_check_proxy_requests check][71], if the check matches three proxy entities, you will get a single burst of three check executions (with the resulting events) every 60 seconds. +Use the `splay` and `splay_coverage` attributes to distribute the three check executions over the specified check interval instead of all at the same time. + +The following example adds `splay` set to `true` and `splay_coverage` set to `90` within the [`proxy_requests` object][37]. +With this addition, instead of three check executions in a single burst every 60 seconds, Sensu will distribute the three check executions evenly across a 54-second period (90% of the 60-second interval): + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: proxy_check_proxy_requests +spec: + command: http_check.sh {{ .labels.url }} + handlers: + - slack + interval: 60 + proxy_requests: + entity_attributes: + - entity.labels.proxy_type == 'website' + splay: true + splay_coverage: 90 + publish: true + round_robin: true + subscriptions: + - run_proxies +{{< /code >}} + +{{< code json >}} +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "proxy_check_proxy_requests" + }, + "spec": { + "command": "http_check.sh {{ .labels.url }}", + "handlers": [ + "slack" + ], + "interval": 60, + "proxy_requests": { + "entity_attributes": [ + "entity.labels.proxy_type == 'website'" + ], + "splay": true, + "splay_coverage": 90 + }, + "publish": true, + "round_robin": true, + "subscriptions": [ + "run_proxies" + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Check token substitution + +Sensu check definitions may include attributes that you wish to override on an entity-by-entity basis. +For example, [check commands][4], which may include command line arguments for controlling the behavior of the check command, may benefit from entity-specific thresholds. +Sensu check tokens are check definition placeholders that the Sensu agent will replace with the corresponding entity definition attribute values (including custom attributes). + +Learn how to use check tokens with the [Sensu tokens reference documentation][5]. + +{{% notice note %}} +**NOTE**: Check tokens are processed before check execution, so token substitutions will not apply to check data delivered via the local agent socket input. +{{% /notice %}} + +## Subdues + +Use the [`subdues` attribute][82] in check definitions to set specific periods of time when Sensu should not execute the check. +Subdues allow you to schedule alert-free periods of time, such as during sleeping hours, weekends, or special maintenance periods. + +You can set more than one subdue at a time. +Each subdue includes a begin and end time as well as how often to repeat the subdue, if desired. + +For example, this check will be subdued (in other words, will not be executed) from 5:00 p.m. until 8:00 a.m. PDT on every weekday, and for the entire day on weekends, as well as every Friday from 10:00 until 11:00 a.m. PDT: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: check_cpu +spec: + command: check-cpu-usage -w 75 -c 90 + interval: 60 + handlers: + - slack + publish: true + round_robin: false + runtime_assets: + - check-cpu-usage + subdues: + - begin: "2022-04-18T17:00:00-07:00" + end: "2022-04-19T08:00:00-07:00" + repeat: + - weekdays + - begin: "2022-04-23T00:00:00-07:00" + end: "2022-04-23T23:59:59-07:00" + repeat: + - weekends + - begin: "2022-04-22T10:00:00-07:00" + end: "2022-04-22T11:00:00-07:00" + repeat: + - fridays + subscriptions: + - system +{{< /code >}} + +{{< code json >}} +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "check_cpu" + }, + "spec": { + "command": "check-cpu-usage -w 75 -c 90", + "interval": 60, + "handlers": [ + "slack" + ], + "publish": true, + "round_robin": false, + "runtime_assets": [ + "check-cpu-usage" + ], + "subdues": [ + { + "begin": "2022-04-18T17:00:00-07:00", + "end": "2022-04-19T08:00:00-07:00", + "repeat": [ + "weekdays" + ] + }, + { + "begin": "2022-04-23T00:00:00-07:00", + "end": "2022-04-23T23:59:59-07:00", + "repeat": [ + "weekends" + ] + }, + { + "begin": "2022-04-22T10:00:00-07:00", + "end": "2022-04-22T11:00:00-07:00", + "repeat": [ + "fridays" + ] + } + ], + "subscriptions": [ + "system" + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +### Subdues and repeat + +If you include a `repeat` array in a `subdues` object, Sensu will start the subdue period on the date you specify. +After the first subdue, Sensu uses the `begin` and `end` values only to determine the *time* of day to start and stop the subdue. + +{{% notice note %}} +**NOTE**: Check subdue repeats are based on the specified `begin` and `end` times and not duration or the difference between the `begin` and `end` times. +Read [Repeat and multi-day subdues](#repeat-and-multi-day-subdues) for more information. +{{% /notice %}} + +In the above example, on April 18, 2022, Sensu will apply the `weekdays` subdue at 5:00 p.m. PDT and end it on April 19 at 8:00 a.m. PDT. +On April 19, Sensu will apply the `weekdays` subdue again at 5:00 p.m. PDT and end it on April 20 at 8:00 a.m. PDT, and so on. + +#### Valid values for repeat arrays + +This table lists and describes valid values for the `repeat` array: + +Value | Description | +----- | ----------- | +`mondays` `tuesdays` `wednesdays` `thursdays` `fridays` `saturdays` `sundays` | Subdue on the specified day, at the same time of day +`weekdays` | Subdue on all Mondays, Tuesdays, Wednesdays, Thursdays, and Fridays, at the same time of day +`weekends` | Subdue on all Saturdays and Sundays, at the same time of day +`daily` | Subdue once every day, at the same time of day +`weekly` | Subdue once per week on the same day, at the same time of day +`monthly` | Subdue once per month on the same day, at the same time of day +`annually` | Subdue once per year on the same day, at the same time of day + +#### Repeat and multi-day subdues + +Because repeat schedules for subdues are based only on the specified time of day, you may need to configure more than one repeat for multi-day subdues. + +For example, suppose that you want to subdue a check on the weekends. +You might set a repeat that starts on a Friday at 5:00 p.m. PDT and ends on Monday at 8:00 a.m. PDT: + +{{< language-toggle >}} + +{{< code yml >}} +subdues: +- begin: "2022-05-06T17:00:00-07:00" + end: "2022-05-09T08:00:00-07:00" + repeat: + - fridays +{{< /code >}} + +{{< code json >}} +{ + "subdues": [ + { + "begin": "2022-05-06T17:00:00-07:00", + "end": "2022-05-09T08:00:00-07:00", + "repeat": [ + "fridays" + ] + } + ] +} +{{< /code >}} + +{{< /language-toggle >}} + +The first weekend, your repeat will work as expected to subdue the check from 5:00 p.m. PDT on Friday until 8:00 a.m. PDT on Monday. + +After the first weekend, the subdue will start as expected at 5:00 p.m. PDT on Friday, but it will expire at 8:00 a.m. PDT on *Saturday* instead of Monday. +This is because after the first instance, repeats are based only on the specified `begin` and `end` times. +Sensu uses the dates to schedule only the first subdue. + +Instead, use the following three-part configuration to achieve the desired repeat schedule (every Friday at 5:00 p.m. PDT until Monday at 8:00 a.m. PDT): + +{{< language-toggle >}} + +{{< code yml >}} +subdues: +- begin: "2022-05-06T17:00:00-07:00" + end: "2022-05-06T23:59:59-07:00" + repeat: + - fridays +- begin: "2022-05-07T00:00:00-07:00" + end: "2022-05-07T23:59:59-07:00" + repeat: + - weekends +- begin: "2022-05-09T00:00:00-07:00" + end: "2022-05-09T08:00:00-07:00" + repeat: + - mondays +{{< /code >}} + +{{< code json >}} +{ + "subdues": [ + { + "begin": "2022-05-06T17:00:00-07:00", + "end": "2022-05-06T23:59:59-07:00", + "repeat": [ + "fridays" + ] + }, + { + "begin": "2022-05-07T00:00:00-07:00", + "end": "2022-05-07T23:59:59-07:00", + "repeat": [ + "weekends" + ] + }, + { + "begin": "2022-05-09T00:00:00-07:00", + "end": "2022-05-09T08:00:00-07:00", + "repeat": [ + "mondays" + ] + } + ] +} +{{< /code >}} + +{{< /language-toggle >}} + +With this configuration, the repeat schedule will subdue the check every Friday from 5:00 p.m. PDT until midnight, the entire 24 hours on every Saturday and Sunday, and every Monday from midnight until 8:00 a.m. PDT. + +## Check hooks + +Check hooks are commands run by the Sensu agent in response to the result of check command execution. +The Sensu agent will execute the appropriate configured hook command, depending on the check execution status (for example, `0`, `1`, or `2`). + +Learn how to use check hooks with the [Sensu hooks reference documentation][6]. + +## Check specification + +### Top-level attributes + +api_version | +-------------|------ +description | Top-level attribute that specifies the Sensu API group and version. For checks in this version of Sensu, this attribute should always be `core/v2`. +required | Required for check definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][41]. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +api_version: core/v2 +{{< /code >}} +{{< code json >}} +{ + "api_version": "core/v2" +} +{{< /code >}} +{{< /language-toggle >}} + +metadata | +-------------|------ +description | Top-level collection of metadata about the check, including `name`, `namespace`, and `created_by` as well as custom `labels` and `annotations`. The `metadata` map is always at the top level of the check definition. This means that in `wrapped-json` and `yaml` formats, the `metadata` scope occurs outside the `spec` scope. Read [metadata attributes][25] for details. +required | Required for check definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][41]. +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +metadata: + name: sensu-site-perf + namespace: development + created_by: admin + labels: + region: us-west-1 + environment: dev + annotations: + slack-channel: "#monitoring" + managed-by: ops + playbooks: www.playbooks-example.url +{{< /code >}} +{{< code json >}} +{ + "metadata": { + "name": "sensu-site-perf", + "namespace": "development", + "created_by": "admin", + "labels": { + "region": "us-west-1", + "environment": "dev" + }, + "annotations": { + "slack-channel": "#monitoring", + "managed-by": "ops", + "playbooks": "www.playbooks-example.url" + } + } +} +{{< /code >}} +{{< /language-toggle >}} + +spec | +-------------|------ +description | Top-level map that includes the check [spec attributes][42]. +required | Required for check definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][41]. +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +spec: + check_hooks: null + command: collect.sh + discard_output: true + env_vars: null + handlers: [] + high_flap_threshold: 0 + interval: 10 + low_flap_threshold: 0 + output_metric_format: prometheus_text + output_metric_tags: + - name: instance + value: '{{ .name }}' + - name: namespace + value: "{{ .namespace }}" + - name: service + value: '{{ .labels.service }}' + output_metric_thresholds: + - name: system_mem_used + tags: null + null_status: 0 + thresholds: + - max: "75.0" + min: "" + status: 1 + - max: "90.0" + min: "" + status: 2 + - name: system_host_processes + tags: + - name: namespace + value: production + null_status: 0 + thresholds: + - max: "50" + min: "5" + status: 1 + - max: "75" + min: "2" + status: 2 + pipelines: + - type: Pipeline + api_version: core/v2 + name: prometheus_gateway_workflows + proxy_entity_name: "" + publish: true + round_robin: false + runtime_assets: null + stdin: false + subscriptions: + - system + timeout: 0 + ttl: 0 +{{< /code >}} +{{< code json >}} +{ + "spec": { + "check_hooks": null, + "command": "collect.sh", + "discard_output": true, + "env_vars": null, + "handlers": [ + + ], + "high_flap_threshold": 0, + "interval": 10, + "low_flap_threshold": 0, + "output_metric_format": "prometheus_text", + "output_metric_tags": [ + { + "name": "instance", + "value": "{{ .name }}" + }, + { + "name": "namespace", + "value": "{{ .namespace }}" + }, + { + "name": "service", + "value": "{{ .labels.service }}" + } + ], + "output_metric_thresholds": [ + { + "name": "system_mem_used", + "tags": null, + "null_status": 0, + "thresholds": [ + { + "max": "75.0", + "min": "", + "status": 1 + }, + { + "max": "90.0", + "min": "", + "status": 2 + } + ] + }, + { + "name": "system_host_processes", + "tags": [ + { + "name": "namespace", + "value": "production" + } + ], + "null_status": 0, + "thresholds": [ + { + "max": "50", + "min": "5", + "status": 1 + }, + { + "max": "75", + "min": "2", + "status": 2 + } + ] + } + ], + "pipelines": [ + { + "type": "Pipeline", + "api_version": "core/v2", + "name": "prometheus_gateway_workflows" + } + ], + "proxy_entity_name": "", + "publish": true, + "round_robin": false, + "runtime_assets": null, + "stdin": false, + "subscriptions": [ + "system" + ], + "timeout": 0, + "ttl": 0 + } +} +{{< /code >}} +{{< /language-toggle >}} + +type | +-------------|------ +description | Top-level attribute that specifies the [`sensuctl create`][41] resource type. Checks should always be type `CheckConfig`. +required | Required for check definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][41]. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +type: CheckConfig +{{< /code >}} +{{< code json >}} +{ + "type": "CheckConfig" +} +{{< /code >}} +{{< /language-toggle >}} + +### Metadata attributes + +| annotations | | +-------------|------ +description | Non-identifying metadata to include with observation event data that you can access with [event filters][27]. You can use annotations to add data that's meaningful to people or external tools that interact with Sensu.

    In contrast to labels, you cannot use annotations in [API response filtering][54], [sensuctl response filtering][55], or [web UI views][61]. +required | false +type | Map of key-value pairs. Keys and values can be any valid UTF-8 string. +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +annotations: + slack-channel: "#monitoring" + managed-by: ops + playbooks: www.playbooks-example.url +{{< /code >}} +{{< code json >}} +{ + "annotations": { + "slack-channel": "#monitoring", + "managed-by": "ops", + "playbooks": "www.playbooks-example.url" + } +} +{{< /code >}} +{{< /language-toggle >}} + +| created_by | | +-------------|------ +description | Username of the Sensu user who created the check or last updated the check. Sensu automatically populates the `created_by` field when the check is created or updated. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +created_by: admin +{{< /code >}} +{{< code json >}} +{ + "created_by": "admin" +} +{{< /code >}} +{{< /language-toggle >}} + +| labels | | +-------------|------ +description | Custom attributes to include with observation event data that you can use for response and web UI view filtering.

    If you include labels in your event data, you can filter [API responses][54], [sensuctl responses][55], and [web UI views][58] based on them. In other words, labels allow you to create meaningful groupings for your data.

    Limit labels to metadata you need to use for response filtering. For complex, non-identifying metadata that you will *not* need to use in response filtering, use annotations rather than labels. +required | false +type | Map of key-value pairs. Keys can contain only letters, numbers, and underscores and must start with a letter. Values can be any valid UTF-8 string. +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +labels: + region: us-west-1 + environment: dev +{{< /code >}} +{{< code json >}} +{ + "labels": { + "region": "us-west-1", + "environment": "dev" + } +} +{{< /code >}} +{{< /language-toggle >}} + +| name | | +-------------|------ +description | Unique string used to identify the check. Check names cannot contain special characters or spaces (validated with Go regex [`\A[\w\.\-]+\z`][53]). Each check must have a unique name within its namespace. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +name: sensu-site-perf +{{< /code >}} +{{< code json >}} +{ + "name": "sensu-site-perf" +} +{{< /code >}} +{{< /language-toggle >}} + +| namespace | | +-------------|------ +description | [Sensu RBAC namespace][26] that the check belongs to. +required | false +type | String +default | `default` +example | {{< language-toggle >}} +{{< code yml >}} +namespace: development +{{< /code >}} +{{< code json >}} +{ + "namespace": "development" +} +{{< /code >}} +{{< /language-toggle >}} + +### Spec attributes + +{{% notice note %}} +**NOTE**: Spec attributes are not required when sending an HTTP `POST` request to the [agent events API](../agent/#events-post) or the [backend core/v2/events API](../../../api/core/events/#create-a-new-event). +When doing so, the spec attributes are listed as individual [top-level attributes](#top-level-attributes) in the check definition instead. +{{% /notice %}} + + + +|check_hooks | | +-------------|------ +description | Array of check response types with respective arrays of [Sensu hook names][6]. Sensu hooks are commands run by the Sensu agent in response to the result of the check command execution. Hooks are executed in order of precedence based on their severity type: `1` to `255`, `ok`, `warning`, `critical`, `unknown`, and finally `non-zero`. +required | false +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +check_hooks: +- '1': + - playbook-warning + - collect-diagnostics +- critical: + - playbook-critical + - collect-diagnostics + - process-tree +{{< /code >}} +{{< code json >}} +{ + "check_hooks": [ + { + "1": [ + "playbook-warning", + "collect-diagnostics" + ] + }, + { + "critical": [ + "playbook-critical", + "collect-diagnostics", + "process-tree" + ] + } + ] +} +{{< /code >}} +{{< /language-toggle >}} + +|command | | +-------------|------ +description | Check command to be executed. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +command: http-perf --url https://sensu.io --warning 1s --critical 2s +{{< /code >}} +{{< code json >}} +{ + "command": "http-perf --url https://sensu.io --warning 1s --critical 2s" +} +{{< /code >}} +{{< /language-toggle >}} + +|cron | | +-------------|------ +description | When the check should be executed, using [cron syntax][14] or a [predefined schedule][15]. Use a prefix of `TZ=` or `CRON_TZ=` to set a [timezone][30] for the cron attribute. {{% notice note %}} +**NOTE**: If you're using YAML to create a check that uses cron scheduling and the first character of the cron schedule is an asterisk (`*`), place the entire cron schedule inside single or double quotes (for example, `cron: '* * * * *'`). +{{% /notice %}} +required | true (unless `interval` is configured) +type | String +example | {{< language-toggle >}} +{{< code yml >}} +cron: 0 0 * * * +{{< /code >}} +{{< code json >}} +{ + "cron": "0 0 * * *" +} +{{< /code >}} +{{< /language-toggle >}} + +|env_vars | | +-------------|------ +description | Array of environment variables to use with command execution. {{% notice note %}} +**NOTE**: To add `env_vars` to a check, use [`sensuctl create`](../../../sensuctl/create-manage-resources/#create-resources). +{{% /notice %}} +required | false +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +env_vars: +- APP_VERSION=2.5.0 +- CHECK_HOST=my.host.internal +{{< /code >}} +{{< code json >}} +{ + "env_vars": [ + "APP_VERSION=2.5.0", + "CHECK_HOST=my.host.internal" + ] +} +{{< /code >}} +{{< /language-toggle >}} + + + +|handlers | | +-------------|------ +description | Array of Sensu event handlers (names) to use for events created by the check. Each array item must be a string. {{% notice note %}} +**NOTE**: The names of [Sumo Logic metrics handlers](../../observe-process/sumo-logic-metrics-handlers/) and [TCP stream handlers](../../observe-process/tcp-stream-handlers/) are not valid values for the handlers array. +Only [traditional handlers](../../observe-process/handlers/) are valid for the handlers array.

    +To use Sumo Logic metrics or TCP stream handlers, include them in a [pipeline](../../observe-process/pipelines/) workflow and reference the pipeline name in the check [pipelines array](#pipelines-attribute). +{{% /notice %}} +required | false +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +handlers: +- pagerduty +- slack +{{< /code >}} +{{< code json >}} +{ + "handlers": [ + "pagerduty", + "slack" + ] +} +{{< /code >}} +{{< /language-toggle >}} + + + +|high_flap_threshold || +-------------|------ +description | Flap detection high threshold (% state change) for the check. Sensu uses the same flap detection algorithm as [Nagios][16]. Read the [event reference][62] to learn more about how Sensu uses the `high_flap_threshold` value. +required | true (if `low_flap_threshold` is configured) +type | Integer +example | {{< language-toggle >}} +{{< code yml >}} +high_flap_threshold: 60 +{{< /code >}} +{{< code json >}} +{ + "high_flap_threshold": 60 +} +{{< /code >}} +{{< /language-toggle >}} + +|interval | | +-------------|------ +description | How often the check is executed. In seconds. +required | true (unless `cron` is configured) +type | Integer +example | {{< language-toggle >}} +{{< code yml >}} +interval: 60 +{{< /code >}} +{{< code json >}} +{ + "interval": 60 +} +{{< /code >}} +{{< /language-toggle >}} + + + +|low_flap_threshold || +-------------|------ +description | Flap detection low threshold (% state change) for the check. Sensu uses the same flap detection algorithm as [Nagios][16]. Read the [event reference][62] to learn more about how Sensu uses the `low_flap_threshold` value. +required | false +type | Integer +example | {{< language-toggle >}} +{{< code yml >}} +low_flap_threshold: 20 +{{< /code >}} +{{< code json >}} +{ + "low_flap_threshold": 20 +} +{{< /code >}} +{{< /language-toggle >}} + + + +|output_metric_format | | +-------------|------ +description | Metric format generated by the check command. Sensu supports the following metric formats:
    `nagios_perfdata` ([Nagios Performance Data][46])
    `graphite_plaintext` ([Graphite Plaintext Protocol][47])
    `influxdb_line` ([InfluxDB Line Protocol][48])
    `opentsdb_line` ([OpenTSDB Data Specification][49])
    `prometheus_text` ([Prometheus Exposition Text][18])

    When a check includes an `output_metric_format`, Sensu will extract the metrics from the check output and add them to the event data in [Sensu metric format][50]. Read [Collect metrics with Sensu checks][23]. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +output_metric_format: +- nagios_perfdata +{{< /code >}} +{{< code json >}} +{ + "output_metric_format": [ + "nagios_perfdata" + ] +} +{{< /code >}} +{{< /language-toggle >}} + + + +|output_metric_handlers | | +-------------|------ +description | Array of Sensu handlers to use for events created by the check. Each array item must be a string. Use `output_metric_handlers` in place of the `handlers` attribute if `output_metric_format` is configured. Metric handlers must be able to process [Sensu metric format][50]. The [Sensu InfluxDB handler][51] provides an example. +required | false +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +output_metric_handlers: +- influx-db +{{< /code >}} +{{< code json >}} +{ + "output_metric_handlers": [ + "influx-db" + ] +} +{{< /code >}} +{{< /language-toggle >}} + + + +|output_metric_tags | | +-------------|------ +description | Custom tags to enrich metric points produced by check output metric extraction. One [name/value pair][22] make up a single tag. The `output_metric_tags` array can contain multiple tags.

    You can use [check token substitution][39] for the `value` attribute in output metric tags. +required | false +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +output_metric_tags: +- name: instance + value: "{{ .name }}" +- name: region + value: "{{ .labels.region }}" +{{< /code >}} +{{< code json >}} +{ + "output_metric_tags": [ + { + "name": "instance", + "value": "{{ .name }}" + }, + { + "name": "region", + "value": "{{ .labels.region }}" + } + ] +} +{{< /code >}} +{{< /language-toggle >}} + + + +|output_metric_thresholds | | +-------------|------ +description | Array of metric names and threshold values to compare to check output metrics for [metric threshold evaluation][79].{{% notice note %}} +**NOTE**: To apply metric threshold evaluation, check definitions must include the [`output_metric_format`](#output-metric-format) attribute with a value that specifies one of Sensu's [supported output metric formats](../metrics/#supported-output-metric-formats). +{{% /notice %}} +required | false +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +output_metric_thresholds: +- name: system_mem_used + tags: '' + null_status: 0 + thresholds: + - max: '75.0' + min: '' + status: 1 + - max: '90.0' + min: '' + status: 2 +- name: system_host_processes + tags: + - name: namespace + value: production + null_status: 0 + thresholds: + - max: '50' + min: '5' + status: 1 + - max: '75' + min: '2' + status: 2 +{{< /code >}} +{{< code json >}} +{ + "output_metric_thresholds": [ + { + "name": "system_mem_used", + "tags": null, + "null_status": 0, + "thresholds": [ + { + "max": "75.0", + "min": "", + "status": 1 + }, + { + "max": "90.0", + "min": "", + "status": 2 + } + ] + }, + { + "name": "system_host_processes", + "tags": [ + { + "name": "namespace", + "value": "production" + } + ], + "null_status": 0, + "thresholds": [ + { + "max": "50", + "min": "5", + "status": 1 + }, + { + "max": "75", + "min": "2", + "status": 2 + } + ] + } + ] +} +{{< /code >}} +{{< /language-toggle >}} + + + +| pipelines | | +-------------|------ +description | Name, type, and API version for the [pipelines][69] to use for event processing. All the observability events that the check produces will be processed according to the pipelines listed in the pipeline array. Read [pipelines attributes][70] for more information. +required | false +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +pipelines: +- type: Pipeline + api_version: core/v2 + name: incident_alerts +{{< /code >}} +{{< code json >}} +{ + "pipelines": [ + { + "type": "Pipeline", + "api_version": "core/v2", + "name": "incident_alerts" + } + ] +} +{{< /code >}} +{{< /language-toggle >}} + + + +|proxy_entity_name| | +-------------|------ +description | Entity name. Used to create a [proxy entity][20] for an external resource (for example, a network switch). +required | false +type | String +validated | [`\A[\w\.\-]+\z`](https://regex101.com/r/zo9mQU/2) +example | {{< language-toggle >}} +{{< code yml >}} +proxy_entity_name: switch-dc-01 +{{< /code >}} +{{< code json >}} +{ + "proxy_entity_name": "switch-dc-01" +} +{{< /code >}} +{{< /language-toggle >}} + + + +|proxy_requests| | +-------------|------ +description | Assigns a check to run for multiple entities according to their `entity_attributes`. In the example below, the check executes for all entities with entity class `proxy` and the custom proxy type label `website`. The `proxy_requests` attributes allow you to reuse check definitions for a group of entities. For more information, read [Proxy requests attributes][10] and [Monitor external resources with proxy entities][28]. +required | false +type | Hash +example | {{< language-toggle >}} +{{< code yml >}} +proxy_requests: + entity_attributes: + - entity.entity_class == 'proxy' + - entity.labels.proxy_type == 'website' + splay: true + splay_coverage: 90 +{{< /code >}} +{{< code json >}} +{ + "proxy_requests": { + "entity_attributes": [ + "entity.entity_class == 'proxy'", + "entity.labels.proxy_type == 'website'" + ], + "splay": true, + "splay_coverage": 90 + } +} +{{< /code >}} +{{< /language-toggle >}} + + + +|publish | | +-------------|------ +description | `true` if check requests are published for the check. Otherwise, `false`. +required | false +type | Boolean +default | `false` +example | {{< language-toggle >}} +{{< code yml >}} +publish: true +{{< /code >}} +{{< code json >}} +{ + "publish": true +} +{{< /code >}} +{{< /language-toggle >}} + + + +|round_robin | | +-------------|------ +description | When set to `true`, Sensu executes the check once per interval, cycling through each subscribing agent in turn. Read [round robin checks][52] for more information.

    Use the `round_robin` attribute with proxy checks to avoid duplicate events and distribute proxy check executions evenly across multiple agents. Read about [proxy checks][33] for more information.

    To use check [`ttl`][31] and `round_robin` together, your check configuration must also specify a [`proxy_entity_name`][32]. If you do not specify a `proxy_entity_name` when using check `ttl` and `round_robin` together, your check will stop executing. +required | false +type | Boolean +default | `false` +example | {{< language-toggle >}} +{{< code yml >}} +round_robin: true +{{< /code >}} +{{< code json >}} +{ + "round_robin": true +} +{{< /code >}} +{{< /language-toggle >}} + +|runtime_assets | | +-------------|------ +description | Array of [Sensu dynamic runtime assets][9] (names). Required at runtime for the execution of the `command`. +required | false +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +runtime_assets: +- http-checks +{{< /code >}} +{{< code json >}} +{ + "runtime_assets": [ + "http-checks" + ] +} +{{< /code >}} +{{< /language-toggle >}} + + + +|scheduler | | +------------|----- +description | Type of scheduler that schedules the check. Sensu automatically sets the `scheduler` value and overrides any user-entered values. Value may be:
    • `memory` for checks scheduled in-memory
    • `etcd` for checks scheduled with etcd leases and watchers (check attribute `round_robin: true` and [etcd used for event storage][67])
    • `postgres` for checks scheduled with PostgreSQL using transactions and asynchronous notification (check attribute `round_robin: true` and [PostgreSQL used for event storage][67] with datastore attribute `enable_round_robin: true`)
    +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +scheduler: postgres +{{< /code >}} +{{< code json >}} +{ + "scheduler": "postgres" +} +{{< /code >}} +{{< /language-toggle >}} + +secrets | +---------------|------ +description | Array of the [name/secret pairs][80] to use with command execution. +required | false +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +secrets: +- name: PAGERDUTY_TOKEN + secret: sensu-pagerduty-token +{{< /code >}} +{{< code json >}} +{ + "secrets": [ + { + "name": "PAGERDUTY_TOKEN", + "secret": "sensu-pagerduty-token" + } + ] +} +{{< /code >}} +{{< /language-toggle >}} + +|silenced | | +-------------|------ +description | Silences that apply to the check. +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +silenced: +- "*:routers" +{{< /code >}} +{{< code json >}} +{ + "silenced": [ + "*:routers" + ] +} +{{< /code >}} +{{< /language-toggle >}} + +|stdin | | +-------------|------ +description | `true` 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. Otherwise, `false`. This attribute cannot be used with existing Sensu check plugins or Nagios plugins because the Sensu agent will wait indefinitely for the check process to read and close stdin. +required | false +type | Boolean +default | `false` +example | {{< language-toggle >}} +{{< code yml >}} +stdin: true +{{< /code >}} +{{< code json >}} +{ + "stdin": true +} +{{< /code >}} +{{< /language-toggle >}} + +|subdue (placeholder) | | +-------------|------ +description | Use the [`subdues`][82] attribute to stop check execution during specific periods. This `subdue` attribute appears in check definitions by default, but it is a placeholder and should not be modified. +example | {{< language-toggle >}} +{{< code yml >}} +subdue: null +{{< /code >}} +{{< code json >}} +{ + "subdue": null +} +{{< /code >}} +{{< /language-toggle >}} + + + +|subdues | | +-------------|------ +description | Specific periods of time when Sensu should not send alerts based on the events the check produces. Use to schedule alert-free periods of time, such as during sleeping hours, weekends, or special maintenance periods. Read [subdues attributes][83] for more information. +required | false +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +subdues: + - begin: "2022-04-18T17:00:00-07:00" + end: "2022-04-19T08:00:00-07:00" + repeat: + - weekdays + - begin: "2022-04-23T00:00:00-07:00" + end: "2022-04-23T23:59:59-07:00" + repeat: + - weekends + - begin: "2022-04-22T10:00:00-07:00" + end: "2022-04-22T11:00:00-07:00" + repeat: + - fridays +{{< /code >}} +{{< code json >}} +{ + "subdues": [ + { + "begin": "2022-04-18T17:00:00-07:00", + "end": "2022-04-19T08:00:00-07:00", + "repeat": [ + "weekdays" + ] + }, + { + "begin": "2022-04-23T00:00:00-07:00", + "end": "2022-04-23T23:59:59-07:00", + "repeat": [ + "weekends" + ] + }, + { + "begin": "2022-04-22T10:00:00-07:00", + "end": "2022-04-22T11:00:00-07:00", + "repeat": [ + "fridays" + ] + } + ] +} +{{< /code >}} +{{< /language-toggle >}} + + + +|subscriptions| | +-------------|------ +description | Array of Sensu entity subscriptions that check requests will be sent to. The array cannot be empty and its items must each be a string. +required | true +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +subscriptions: +- system +{{< /code >}} +{{< code json >}} +{ + "subscriptions": [ + "system" + ] +} +{{< /code >}} +{{< /language-toggle >}} + +|timeout | | +-------------|------ +description | Check execution duration timeout (hard stop). In seconds. +required | false +type | Integer +example | {{< language-toggle >}} +{{< code yml >}} +timeout: 30 +{{< /code >}} +{{< code json >}} +{ + "timeout": 30 +} +{{< /code >}} +{{< /language-toggle >}} + + + +|ttl | | +-------------|------ +description | The time-to-live (TTL) until check results are considered stale. In seconds. If an agent stops publishing results for the check and the TTL expires, an event will be created for the agent's entity.

    The check `ttl` must be greater than the check `interval` and should allow enough time for the check execution and result processing to complete. For example, for a check that has an `interval` of `60` (seconds) and a `timeout` of `30` (seconds), the appropriate `ttl` is at least `90` (seconds).

    To use check `ttl` and [`round_robin`][43] together, your check configuration must also specify a [`proxy_entity_name`][44]. If you do not specify a `proxy_entity_name` when using check `ttl` and `round_robin` together, your check will stop executing. {{% notice note %}} +**NOTE**: Adding TTLs to checks adds overhead, so use the `ttl` attribute sparingly. +{{% /notice %}} +required | false +type | Integer +example | {{< language-toggle >}} +{{< code yml >}} +ttl: 100 +{{< /code >}} +{{< code json >}} +{ + "ttl": 100 +} +{{< /code >}} +{{< /language-toggle >}} + +#### Check output truncation attributes + +|max_output_size | | +-------------|------- +description | Maximum size of stored check outputs. In bytes. When set to a non-zero value, the Sensu backend truncates check outputs larger than this value before storing to etcd. `max_output_size` does not affect data sent to Sensu filters, mutators, and handlers.

    When check output is truncated due to the `max_output_size` configuration, the events the check produces will include the label `sensu.io/output_truncated_bytes`. +required | false +type | Integer +example | {{< language-toggle >}} +{{< code yml >}} +max_output_size: 1024 +{{< /code >}} +{{< code json >}} +{ + "max_output_size": 1024 +} +{{< /code >}} +{{< /language-toggle >}} + +|discard_output | | +-------------|------ +description | If `true`, discard check output after extracting metrics. No check output will be sent to the Sensu backend. Otherwise, `false`. +required | false +type | Boolean +example | {{< language-toggle >}} +{{< code yml >}} +discard_output: true +{{< /code >}} +{{< code json >}} +{ + "discard_output": true +} +{{< /code >}} +{{< /language-toggle >}} + +#### `output_metric_tags` attributes + +name | +-------------|------ +description | Name for the [output metric tag][19]. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +name: instance +{{< /code >}} +{{< code json >}} +{ + "name": "instance" +} +{{< /code >}} +{{< /language-toggle >}} + +value | +-------------|------ +description | Value for the [output metric tag][19]. Use [check token substitution][39] syntax for the `value` attribute, with dot-notation access to any event attribute. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +value: {{ .name }} +{{< /code >}} +{{< code json >}} +{ + "value": "{{ .name }}" +} +{{< /code >}} +{{< /language-toggle >}} + +#### `output_metric_thresholds` attributes + +name | +-------------|------ +description | Name of the metric to use for [metric threshold evaluation][79]. Must match the [event.metrics.points[].name][81] value for a metric point in the check results.{{% notice note %}} +**NOTE**: To produce values for the output metrics you specify, the check definition must include a valid [`output_metric_format`](#output-metric-format). +{{% /notice %}} +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +name: system_host_processes +{{< /code >}} +{{< code json >}} +{ + "name": "system_host_processes" +} +{{< /code >}} +{{< /language-toggle >}} + +null_status | +-------------|------ +description | Event [check status][77] to use if a metric specified for [metric threshold evaluation][79] is missing from the event data.{{% notice note %}} +**NOTE**: Sensu only overrides the event check status if it is less than the specified `null_status` value. +{{% /notice %}} +required | false +type | Integer +default | `0` +example | {{< language-toggle >}} +{{< code yml >}} +null_status: 0 +{{< /code >}} +{{< code json >}} +{ + "null_status": 0 +} +{{< /code >}} +{{< /language-toggle >}} + +tags | +-------------|------ +description | Tags of the metric to use for [metric threshold evaluation][79]. If provided, must match the [event.metrics.points[].tags][81] name and value for a metric point in the check results. Read [tags attributes][76] for more information. +required | false +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +tags: +- name: namespace + value: production +{{< /code >}} +{{< code json >}} +{ + "tags": [ + { + "name": "namespace", + "value": "production" + } + ] +} +{{< /code >}} +{{< /language-toggle >}} + +thresholds | +-------------|------ +description | Rules to apply for [metric threshold evaluation][79]. Read [thresholds attributes][75] for more information. +required | true +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +thresholds: +- max: '50' + min: '5' + status: 1 +- max: '75' + min: '2' + status: 2 +{{< /code >}} +{{< code json >}} +{ + "thresholds": [ + { + "max": "50", + "min": "5", + "status": 1 + }, + { + "max": "75", + "min": "2", + "status": 2 + } + ] +} +{{< /code >}} +{{< /language-toggle >}} + +#### Pipelines attributes + +api_version | +-------------|------ +description | The Sensu API group and version for the [pipeline][69]. For pipelines in this version of Sensu, the api_version should always be `core/v2`. +required | true +type | String +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +api_version: core/v2 +{{< /code >}} +{{< code json >}} +{ + "api_version": "core/v2" +} +{{< /code >}} +{{< /language-toggle >}} + +name | +-------------|------ +description | Name of the Sensu [pipeline][69] for the check to use. +required | true +type | String +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +name: incident_alerts +{{< /code >}} +{{< code json >}} +{ + "name": "incident_alerts" +} +{{< /code >}} +{{< /language-toggle >}} + +type | +-------------|------ +description | The [`sensuctl create`][41] resource type for the [pipeline][69]. Pipelines should always be type `Pipeline`. +required | true +type | String +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +type: Pipeline +{{< /code >}} +{{< code json >}} +{ + "type": "Pipeline" +} +{{< /code >}} +{{< /language-toggle >}} + +#### Proxy requests attributes + +|entity_attributes| | +-------------|------ +description | Sensu entity attributes to match entities in the registry using [Sensu query expressions][11]. +required | false +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +entity_attributes: +- entity.entity_class == 'proxy' +- entity.labels.proxy_type == 'website' +{{< /code >}} +{{< code json >}} +{ + "entity_attributes": [ + "entity.entity_class == 'proxy'", + "entity.labels.proxy_type == 'website'" + ] +} +{{< /code >}} +{{< /language-toggle >}} + + + +|splay | | +-------------|------ +description | `true` if proxy check requests should be splayed, published evenly over a window of time, determined by the check interval and a configurable [`splay_coverage`][73] percentage. Otherwise, `false`. +required | false +type | Boolean +default | `false` +example | {{< language-toggle >}} +{{< code yml >}} +splay: true +{{< /code >}} +{{< code json >}} +{ + "splay": true +} +{{< /code >}} +{{< /language-toggle >}} + + + +|splay_coverage | | +-------------|------ +description | **Percentage** of the check interval over which Sensu can execute the check for all applicable entities, as defined in the entity attributes. Sensu uses the splay_coverage attribute to determine the period of time to publish check requests over, before the next check interval begins.

    For example, if a check's interval is 60 seconds and `splay_coverage` is 90, Sensu will distribute its proxy check requests evenly over a time window of 54 seconds (60 seconds * 90%). This leaves 6 seconds after the last proxy check execution before the the next round of proxy check requests for the same check. +required | `true` if [`splay`][72] attribute is set to `true` (otherwise, `false`) +type | Integer +example | {{< language-toggle >}} +{{< code yml >}} +splay_coverage: 90 +{{< /code >}} +{{< code json >}} +{ + "splay_coverage": 90 +} +{{< /code >}} +{{< /language-toggle >}} + +#### `secrets` attributes + +name | +-------------|------ +description | Name of the [secret][56] defined in the executable command. Becomes the environment variable presented to the check. Read [Use secrets management in Sensu][59] for more information. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +name: ANSIBLE_HOST +{{< /code >}} +{{< code json >}} +{ + "name": "ANSIBLE_HOST" +} +{{< /code >}} +{{< /language-toggle >}} + +secret | +-------------|------ +description | Name of the Sensu secret resource that defines how to retrieve the [secret][56]. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +secret: sensu-ansible-host +{{< /code >}} +{{< code json >}} +{ + "secret": "sensu-ansible-host" +} +{{< /code >}} +{{< /language-toggle >}} + +#### Tags attributes + +name | +-------------|------ +description | Tag name for the metric to use for [metric threshold evaluation][79]. If provided, must match the [event.metrics.points[].tags.name][81] value for a metric point in the check results.{{% notice note %}} +**NOTE**: If provided, you must also provide the value for the same metric point tag. +{{% /notice %}} +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +name: namespace +{{< /code >}} +{{< code json >}} +{ + "name": "namespace" +} +{{< /code >}} +{{< /language-toggle >}} + +value | +-------------|------ +description | Tag value of the metric to use for [metric threshold evaluation][79]. If provided, must match the [event.metrics.points[].tags.value][81] value for a metric point in the check results.{{% notice note %}} +**NOTE**: If provided, you must also provide the name for the same metric point tag. +{{% /notice %}} +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +value: production +{{< /code >}} +{{< code json >}} +{ + "value": "production" +} +{{< /code >}} +{{< /language-toggle >}} + +#### Thresholds attributes + +max | +-------------|------ +description | Maximum threshold for the metric for [metric threshold evaluation][79]. You must provide a thresholds `max` value if you do not provide a `min` value. +required | false (if a thresholds `min` value is provided) +type | String +example | {{< language-toggle >}} +{{< code yml >}} +max: '75' +{{< /code >}} +{{< code json >}} +{ + "max": "75" +} +{{< /code >}} +{{< /language-toggle >}} + +min | +-------------|------ +description | Minimum threshold for the metric for [metric threshold evaluation][79]. You must provide a thresholds `min` value if you do not provide a `max` value. +required | false (if a thresholds `max` value is provided) +type | String +example | {{< language-toggle >}} +{{< code yml >}} +min: '2' +{{< /code >}} +{{< code json >}} +{ + "min": "2" +} +{{< /code >}} +{{< /language-toggle >}} + +status | +-------------|------ +description | Event [check status][77] to use if the check's output metric value is equal to or greater than the specified `max` threshold or equal to or less than the specified `min` threshold in [metric threshold evaluation][79].{{% notice note %}} +**NOTE**: Sensu only overrides the event check status if it is less than the specified threshold `status` value. +{{% /notice %}} You can specify any status value, but [event annotations based on threshold status][78] will display `unknown` if the status does not equal `0`, `1`, or `2`. +required | true +type | Integer +example | {{< language-toggle >}} +{{< code yml >}} +status: 2 +{{< /code >}} +{{< code json >}} +{ + "status": 2 +} +{{< /code >}} +{{< /language-toggle >}} + +#### `subdues` attributes + +begin | +-------------|------ +description | Date and time at which the subdue should begin. In [RFC 3339][84] format with numeric zone offset (`2022-01-01T07:30:00-07:00` or `2022-01-01T14:30:00Z`). +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +begin: "2022-04-18T17:00:00-07:00" +{{< /code >}} +{{< code json >}} +{ + "begin": "2022-04-18T17:00:00-07:00" +} +{{< /code >}} +{{< /language-toggle >}} + +end | +-------------|------ +description | Date and time at which the subdue should end. In [RFC 3339][84] format with numeric zone offset (`2022-01-01T07:30:00-07:00` or `2022-01-01T14:30:00Z`). +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +end: "2022-04-19T08:00:00-07:00" +{{< /code >}} +{{< code json >}} +{ + "end": "2022-04-19T08:00:00-07:00" +} +{{< /code >}} +{{< /language-toggle >}} + +repeat | +-------------|------ +description | Interval at which the subdue should repeat. `weekdays` includes Mondays, Tuesdays, Wednesdays, Thursdays, and Fridays. `weekends` includes Saturdays and Sundays. Read [Subdues and repeat][85] for more information.{{% notice note %}} +**NOTE**: Check subdue repeats are based on the specified `begin` and `end` times and not duration or the difference between the `begin` and `end` times. +{{% /notice %}} +required | false +type | Array +allowed values | `mondays`, `tuesdays`, `wednesdays`, `thursdays`, `fridays`, `saturdays`, `sundays`, `weekdays`, `weekends`, `daily`, `weekly`, `monthly`, `annually` +example | {{< language-toggle >}} +{{< code yml >}} +repeat: +- weekdays +{{< /code >}} +{{< code json >}} +{ + "repeat": [ + "weekdays" + ] +} +{{< /code >}} +{{< /language-toggle >}} + +## Metric check example + +The following example shows the resource definition for a check that collects [metrics][68] in Nagios Performance Data format: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: CheckConfig +api_version: core/v2 +metadata: + annotations: + slack-channel: '#monitoring' + labels: + region: us-west-1 + name: collect-metrics +spec: + check_hooks: null + command: collect.sh + discard_output: true + env_vars: null + handlers: [] + high_flap_threshold: 0 + interval: 10 + low_flap_threshold: 0 + output_metric_format: prometheus_text + output_metric_tags: + - name: instance + value: '{{ .name }}' + - name: namespace + value: '{{ .namespace }}' + - name: service + value: '{{ .labels.service }}' + output_metric_thresholds: + - name: system_mem_used + tags: null + null_status: 1 + thresholds: + - max: "75.0" + min: "" + status: 1 + - max: "90.0" + min: "" + status: 2 + - name: system_host_processes + tags: + - name: namespace + value: production + null_status: 1 + thresholds: + - max: "50" + min: "5" + status: 1 + - max: "75" + min: "2" + status: 2 + pipelines: + - type: Pipeline + api_version: core/v2 + name: prometheus_gateway_workflows + proxy_entity_name: "" + publish: true + round_robin: false + runtime_assets: null + stdin: false + subscriptions: + - system + timeout: 0 + ttl: 0 +{{< /code >}} + +{{< code json >}} +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "annotations": { + "slack-channel": "#monitoring" + }, + "labels": { + "region": "us-west-1" + }, + "name": "collect-metrics" + }, + "spec": { + "check_hooks": null, + "command": "collect.sh", + "discard_output": true, + "env_vars": null, + "handlers": [], + "high_flap_threshold": 0, + "interval": 10, + "low_flap_threshold": 0, + "output_metric_format": "prometheus_text", + "output_metric_tags": [ + { + "name": "instance", + "value": "{{ .name }}" + }, + { + "name": "namespace", + "value": "{{ .namespace }}" + }, + { + "name": "service", + "value": "{{ .labels.service }}" + } + ], + "output_metric_thresholds": [ + { + "name": "system_mem_used", + "tags": null, + "null_status": 1, + "thresholds": [ + { + "max": "75.0", + "min": "", + "status": 1 + }, + { + "max": "90.0", + "min": "", + "status": 2 + } + ] + }, + { + "name": "system_host_processes", + "tags": [ + { + "name": "namespace", + "value": "production" + } + ], + "null_status": 1, + "thresholds": [ + { + "max": "50", + "min": "5", + "status": 1 + }, + { + "max": "75", + "min": "2", + "status": 2 + } + ] + } + ], + "pipelines": [ + { + "type": "Pipeline", + "api_version": "core/v2", + "name": "prometheus_gateway_workflows" + } + ], + "proxy_entity_name": "", + "publish": true, + "round_robin": false, + "runtime_assets": null, + "stdin": false, + "subscriptions": [ + "system" + ], + "timeout": 0, + "ttl": 0 + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Check example that uses secrets management + +The check in the following example uses [secrets management][59] to keep a GitHub token private. +Learn more about secrets management for your Sensu configuration in the [secrets][56] and [secrets providers][57] references. + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: ping-github-api +spec: + check_hooks: null + command: ping-github-api.sh $GITHUB_TOKEN + secrets: + - name: GITHUB_TOKEN + secret: github-token-vault +{{< /code >}} + +{{< code json >}} +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "ping-github-api" + }, + "spec": { + "check_hooks": null, + "command": "ping-github-api.sh $GITHUB_TOKEN", + "secrets": [ + { + "name": "GITHUB_TOKEN", + "secret": "github-token-vault" + } + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Check example with a PowerShell script command + +If you use a PowerShell script in your check command, make sure to include the `-f` flag in the command. +The `-f` flag ensures that the proper exit code is passed into Sensu. +For example: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: interval_test +spec: + command: powershell.exe -f c:\\users\\tester\\test.ps1 + subscriptions: + - system + interval: 60 + pipelines: + - type: Pipeline + api_version: core/v2 + name: interval_pipeline + publish: true +{{< /code >}} + +{{< code json >}} +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "interval_test" + }, + "spec": { + "command": "powershell.exe -f c:\\\\users\\ ester\\ est.ps1", + "subscriptions": [ + "system" + ], + "interval": 60, + "pipelines": [ + { + "type": "Pipeline", + "api_version": "core/v2", + "name": "interval_pipeline" + } + ], + "publish": true + } +} +{{< /code >}} + +{{< /language-toggle >}} + +The dynamic runtime asset reference includes an [example check definition that uses the asset path][60] to correctly capture exit status codes from PowerShell plugins distributed as dynamic runtime assets. + + +[1]: #subscription-checks +[2]: https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern +[3]: https://en.wikipedia.org/wiki/Standard_streams +[4]: #check-commands +[5]: ../tokens/ +[6]: ../hooks/ +[7]: /sensu-core/latest/reference/checks/#standalone-checks +[8]: ../../../operations/control-access/rbac/ +[9]: ../../../plugins/assets/ +[10]: #proxy-requests-attributes +[11]: ../../observe-filter/sensu-query-expressions/ +[12]: ../monitor-server-resources/ +[13]: #check-attributes +[14]: https://en.wikipedia.org/wiki/Cron#CRON_expression +[15]: https://godoc.org/github.com/robfig/cron#hdr-Predefined_schedules +[16]: https://assets.nagios.com/downloads/nagioscore/docs/nagioscore/3/en/flapping.html +[17]: #subdue-attributes +[18]: https://prometheus.io/docs/instrumenting/exposition_formats/#text-based-format +[19]: #output-metric-tags +[20]: ../../observe-entities/#proxy-entities +[21]: ../../observe-entities/entities/#spec-attributes +[22]: #output_metric_tags-attributes +[23]: ../collect-metrics-with-checks/ +[24]: ../../observe-events/events/ +[25]: #metadata-attributes +[26]: ../../../operations/control-access/namespaces/ +[27]: ../../observe-filter/filters/ +[28]: ../../observe-entities/monitor-external-resources/ +[29]: https://bonsai.sensu.io +[30]: https://en.wikipedia.org/wiki/Cron#Time_zone_handling +[31]: #ttl-attribute +[32]: #proxy-entity-name-attribute +[33]: #proxy-checks +[34]: ../../../api/core/checks/#checkscheckexecute-post +[35]: #use-a-proxy-check-to-monitor-a-proxy-entity +[36]: #use-a-proxy-check-to-monitor-multiple-proxy-entities +[37]: #proxy-requests-top-level +[38]: #interval-scheduling +[39]: #check-token-substitution +[40]: ../../observe-entities/entities#manage-entity-labels +[41]: ../../../sensuctl/create-manage-resources/#create-resources +[42]: #spec-attributes +[43]: #round-robin-attribute +[44]: #proxy-entity-name-attribute +[45]: #cron-scheduling +[46]: https://assets.nagios.com/downloads/nagioscore/docs/nagioscore/3/en/perfdata.html +[47]: https://graphite.readthedocs.io/en/latest/feeding-carbon.html#the-plaintext-protocol +[48]: https://docs.influxdata.com/enterprise_influxdb/v1.9/write_protocols/line_protocol_reference/ +[49]: http://opentsdb.net/docs/build/html/user_guide/writing/index.html#data-specification +[50]: ../../observe-events/events/#metrics-attribute +[51]: https://bonsai.sensu.io/assets/sensu/sensu-influxdb-handler +[52]: #round-robin-checks +[53]: https://regex101.com/r/zo9mQU/2 +[54]: ../../../api/#response-filtering +[55]: ../../../sensuctl/filter-responses/ +[56]: ../../../operations/manage-secrets/secrets/ +[57]: ../../../operations/manage-secrets/secrets-providers/ +[58]: ../../../web-ui/search#search-for-labels +[59]: ../../../operations/manage-secrets/secrets-management/ +[60]: ../../../plugins/assets#dynamic-runtime-asset-path +[61]: ../../../web-ui/search/ +[62]: ../../observe-events/events/#flap-detection-algorithm +[63]: #ad-hoc-scheduling +[64]: ../subscriptions/ +[65]: ../../../operations/deploy-sensu/datastore/ +[66]: ../../../operations/deploy-sensu/datastore/#round-robin-postgresql +[67]: #event-storage-for-round-robin-scheduling +[68]: ../metrics/ +[69]: ../../observe-process/pipelines/ +[70]: #pipelines-attributes +[71]: #example-proxy-check-using-proxy_requests +[72]: #splay +[73]: #splay-coverage +[75]: #thresholds-attributes +[76]: #tags-attributes +[77]: ../../observe-events/events/#check-status-attribute +[78]: ../metrics/#add-event-annotations-based-on-metric-threshold-evaluation +[79]: ../metrics/#metric-threshold-evaluation +[80]: #secrets-attributes +[81]: ../../observe-events/events/#points-attributes +[82]: #check-subdues-attribute +[83]: #subdues-attributes +[84]: https://www.ietf.org/rfc/rfc3339.txt +[85]: #subdues-and-repeat +[86]: ../../observe-entities/entities/#proxy-entities-and-round-robin-scheduling diff --git a/content/sensu-go/6.12/observability-pipeline/observe-schedule/collect-metrics-with-checks.md b/content/sensu-go/6.12/observability-pipeline/observe-schedule/collect-metrics-with-checks.md new file mode 100644 index 0000000000..092791f0f7 --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-schedule/collect-metrics-with-checks.md @@ -0,0 +1,494 @@ +--- +title: "Collect service metrics with Sensu checks" +linkTitle: "Collect Service Metrics" +guide_title: "Collect service metrics with Sensu checks" +type: "guide" +description: "Collect service metrics for an NGINX webserver with a Sensu check and output the metrics data in Nagios Performance Data format." +weight: 180 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: observe-schedule +--- + +{{% notice protip %}} +**PRO TIP**: You can use the HTTP Service Monitoring (Local) integration in the [Sensu Catalog](../../../catalog/sensu-catalog/) to collect service metrics instead of following this guide. +Follow the Catalog prompts to configure the Sensu resources you need and start processing your observability data with a few clicks. +{{% /notice %}} + +Sensu checks are commands (or scripts) that the Sensu agent executes that output data and produce an exit code to indicate a state. +If you are unfamiliar with checks, read the [checks reference][1] for details and examples. +You can also learn how to configure monitoring checks in [Monitor server resources][2]. + +This guide demonstrates how to use a check to extract service metrics for an NGINX webserver, with output in [Nagios Performance Data][3] format. + +## Requirements + +To follow this guide, [install][13] the Sensu backend, make sure at least one Sensu [agent][16] is running, and install and configure [sensuctl][17]. + +Before you begin, add the [debug handler][10] to your Sensu instance. +The check in this guide will use it to write metric events to a file for inspection. + +## Configure a Sensu entity + +Every Sensu agent has a defined set of subscriptions that determine which checks the agent will execute. +For an agent to execute a specific check, you must specify the same subscription in the agent configuration and the check definition. +To run the NGINX webserver check, you'll need a Sensu entity with the subscription `webserver`. + +To add the `webserver` subscription to the entity the Sensu agent is observing, first find your agent entity name: + +{{< code shell >}} +sensuctl entity list +{{< /code >}} + +The `ID` is the name of your entity. + +Replace `` with the name of your agent entity in the following sensuctl command. +Then, run: + +{{< code shell >}} +sensuctl entity update +{{< /code >}} + +- For `Entity Class`, press enter. +- For `Subscriptions`, type `webserver` and press enter. + +Confirm both Sensu services are running: + +{{< code shell >}} +systemctl status sensu-backend && systemctl status sensu-agent +{{< /code >}} + +The response should indicate `active (running)` for both the Sensu backend and agent. + +## Register the dynamic runtime asset + +To power the check to collect service metrics, you will use a check in the sensu/http-checks dynamic runtime asset. +Use sensuctl to register the sensu/http-checks dynamic runtime asset: + +{{< code shell >}} +sensuctl asset add sensu/http-checks:0.5.0 -r http-checks +{{< /code >}} + +The response will indicate that the asset was added: + +{{< code text >}} +fetching bonsai asset: sensu/http-checks:0.5.0 +added asset: sensu/http-checks:0.5.0 + +You have successfully added the Sensu asset resource, but the asset will not get downloaded until +it's invoked by another Sensu resource (ex. check). To add this runtime asset to the appropriate +resource, populate the "runtime_assets" field with ["http-checks"]. +{{< /code >}} + +This example uses the -r (rename) flag to specify a shorter name for the dynamic runtime asset: http-checks. + +Use sensuctl to confirm that both the http-checks dynamic runtime asset is ready to use: + +{{< code shell >}} +sensuctl asset list +{{< /code >}} + +The sensuctl response should list http-checks: + +{{< code text >}} + Name URL Hash +────────────── ───────────────────────────────────────────────────────────────────── ────────── + http-checks //assets.bonsai.sensu.io/.../http-checks_0.5.0_windows_amd64.tar.gz 52ae075 + http-checks //assets.bonsai.sensu.io/.../http-checks_0.5.0_darwin_amd64.tar.gz 72d0f15 + http-checks //assets.bonsai.sensu.io/.../http-checks_0.5.0_linux_armv7.tar.gz ef18587 + http-checks //assets.bonsai.sensu.io/.../http-checks_0.5.0_linux_arm64.tar.gz 3504ddf + http-checks //assets.bonsai.sensu.io/.../http-checks_0.5.0_linux_386.tar.gz 60b8883 + http-checks //assets.bonsai.sensu.io/.../http-checks_0.5.0_linux_amd64.tar.gz 1db73a8 +{{< /code >}} + +## Install and configure NGINX + +The webserver check requires a running NGINX service, so you'll need to install and configure NGINX. + +{{% notice note %}} +**NOTE**: You may need to install and update the EPEL repository with `sudo yum install epel-release` and `sudo yum update` before you can install NGINX. +{{% /notice %}} + +Install NGINX: + +{{< code shell >}} +sudo yum install nginx +{{< /code >}} + +Enable and start the NGINX service: + +{{< code shell >}} +systemctl enable nginx && systemctl start nginx +{{< /code >}} + +Verify that NGINX is serving webpages: + +{{< code shell >}} +curl -sI http://localhost +{{< /code >}} + +The response should include `HTTP/1.1 200 OK` to indicate that NGINX processed your request as expected: + +{{< code text >}} +HTTP/1.1 200 OK +Server: nginx/1.20.1 +Date: Tue, 02 Nov 2021 20:15:40 GMT +Content-Type: text/html +Content-Length: 4833 +Last-Modified: Fri, 16 May 2014 15:12:48 GMT +Connection: keep-alive +ETag: "xxxxxxxx-xxxx" +Accept-Ranges: bytes +{{< /code >}} + +With your NGINX service running, you can configure the check to collect service metrics. + +## Create a check to collect metrics + +Create the `collect-metrics` check with a command that uses the `http-perf` performance check from the http-checks dynamic runtime asset: + +{{< code shell >}} +sensuctl check create collect-metrics \ +--command 'http-perf --url http://localhost --warning 1s --critical 2s' \ +--handlers debug \ +--interval 15 \ +--subscriptions webserver \ +--runtime-assets http-checks \ +--output-metric-format nagios_perfdata +{{< /code >}} + +This example check specifies a 15-second interval for collecting metrics, a subscription to ensure the check will run on any entity that includes the `webserver` subscription, the name of the dynamic runtime asset the check needs to work properly, and the `nagios_perfdata` output metric format. + +You should receive a confirmation response: `Created`. + +To view the check resource you just created with sensuctl, run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl check info collect-metrics --format yaml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl check info collect-metrics --format wrapped-json +{{< /code >}} + +{{< /language-toggle >}} + +The sensuctl response will list the complete check resource definition: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: CheckConfig +api_version: core/v2 +metadata: + created_by: admin + name: collect-metrics + namespace: default +spec: + check_hooks: null + command: http-perf --url http://localhost --warning 1s --critical 2s + env_vars: null + handlers: + - debug + high_flap_threshold: 0 + interval: 15 + low_flap_threshold: 0 + output_metric_format: nagios_perfdata + output_metric_handlers: null + pipelines: [] + proxy_entity_name: "" + publish: true + round_robin: false + runtime_assets: + - http-checks + secrets: null + stdin: false + subdue: null + subscriptions: + - webserver + timeout: 0 + ttl: 0 +{{< /code >}} + +{{< code json >}} +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "created_by": "admin", + "name": "collect-metrics", + "namespace": "default" + }, + "spec": { + "check_hooks": null, + "command": "http-perf --url http://localhost --warning 1s --critical 2s", + "env_vars": null, + "handlers": [ + "debug" + ], + "high_flap_threshold": 0, + "interval": 15, + "low_flap_threshold": 0, + "output_metric_format": "nagios_perfdata", + "output_metric_handlers": null, + "pipelines": [ + ], + "proxy_entity_name": "", + "publish": true, + "round_robin": false, + "runtime_assets": [ + "http-checks" + ], + "secrets": null, + "stdin": false, + "subdue": null, + "subscriptions": [ + "webserver" + ], + "timeout": 0, + "ttl": 0 + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Confirm that your check is collecting metrics + +If the check is collecting metrics correctly according to its `output_metric_format`, the metrics will be extracted in Sensu metric format and passed to the observability pipeline for handling. +The Sensu agent will log errors if it cannot parse the check output. + +To confirm that the check extracted metrics, inspect the event passed to the debug handler in the debug-event.json file: + +{{< code shell >}} +cat /var/log/sensu/debug-event.json +{{< /code >}} + +The event will include a top-level metrics section populated with metrics points arrays if the Sensu agent correctly ingested the metrics, similar to this example: + +{{< code text >}} +{ + "check": { + "command": "http-perf --url http://localhost --warning 1s --critical 2s", + "handlers": [ + "debug" + ], + "high_flap_threshold": 0, + "interval": 15, + "low_flap_threshold": 0, + "publish": true, + "runtime_assets": [ + "http-checks" + ], + "subscriptions": [ + "webserver" + ], + "proxy_entity_name": "", + "check_hooks": null, + "stdin": false, + "subdue": null, + "ttl": 0, + "timeout": 0, + "round_robin": false, + "duration": 0.011235081, + "executed": 1635886845, + "history": [ + { + "status": 0, + "executed": 1635886785 + }, + { + "status": 0, + "executed": 1635886800 + }, + { + "status": 0, + "executed": 1635886815 + }, + { + "status": 0, + "executed": 1635886830 + }, + { + "status": 0, + "executed": 1635886845 + } + ], + "issued": 1635886845, + "output": "http-perf OK: 0.001088s | dns_duration=0.000216, tls_handshake_duration=0.000000, connect_duration=0.000140, first_byte_duration=0.001071, total_request_duration=0.001088\n", + "state": "passing", + "status": 0, + "total_state_change": 0, + "last_ok": 1635886845, + "occurrences": 5, + "occurrences_watermark": 5, + "output_metric_format": "nagios_perfdata", + "output_metric_handlers": null, + "env_vars": null, + "metadata": { + "name": "collect-metrics", + "namespace": "default" + }, + "secrets": null, + "is_silenced": false, + "scheduler": "memory", + "processed_by": "sensu-centos", + "pipelines": [] + }, + "metrics": { + "handlers": null, + "points": [ + { + "name": "dns_duration", + "value": 0.000216, + "timestamp": 1635886845, + "tags": null + }, + { + "name": "tls_handshake_duration", + "value": 0, + "timestamp": 1635886845, + "tags": null + }, + { + "name": "connect_duration", + "value": 0.00014, + "timestamp": 1635886845, + "tags": null + }, + { + "name": "first_byte_duration", + "value": 0.001071, + "timestamp": 1635886845, + "tags": null + }, + { + "name": "total_request_duration", + "value": 0.001088, + "timestamp": 1635886845, + "tags": null + } + ] + }, + "metadata": { + "namespace": "default" + }, + "id": "d19ee7f9-8cc5-447b-9059-895e89e14667", + "sequence": 146, + "pipelines": null, + "timestamp": 1635886845, + "entity": { + "entity_class": "agent", + "system": { + "hostname": "sensu-centos", + "os": "linux", + "platform": "centos", + "platform_family": "rhel", + "platform_version": "7.9.2009", + "network": { + "interfaces": [ + { + "name": "lo", + "addresses": [ + "127.0.0.1/8", + "::1/128" + ] + }, + { + "name": "eth0", + "mac": "08:00:27:8b:c9:3f", + "addresses": [ + "10.0.2.15/24", + "fe80::20b8:8cea:fa4:2e57/64" + ] + }, + { + "name": "eth1", + "mac": "08:00:27:40:ab:31", + "addresses": [ + "192.168.200.95/24", + "fe80::a00:27ff:fe40:ab31/64" + ] + } + ] + }, + "arch": "amd64", + "libc_type": "glibc", + "vm_system": "vbox", + "vm_role": "guest", + "cloud_provider": "", + "processes": null + }, + "subscriptions": [ + "webserver", + "entity:sensu-centos" + ], + "last_seen": 1635886845, + "deregister": false, + "deregistration": {}, + "user": "agent", + "redact": [ + "password", + "passwd", + "pass", + "api_key", + "api_token", + "access_key", + "secret_key", + "private_key", + "secret" + ], + "metadata": { + "name": "sensu-centos", + "namespace": "default" + }, + "sensu_agent_version": "6.5.4" + } +} +{{< /code >}} + +## What's next + +Now that you know how to extract metrics from check output, learn to use a metrics handler to [populate service and time-series metrics in InfluxDB][5] or [send data to Sumo Logic][20]. + +Read [Monitor server resources with checks][2] to learn how to monitor an NGINX webserver rather than collect metrics. +You can also learn to use Sensu to [collect Prometheus metrics][14]. + +Learn more about the Sensu resources you created in this guide: + +- [Checks][1] +- [Dynamic runtime assets][19] +- [Handlers][18] and [pipelines][15] +- [Subscriptions][8] + +The events reference includes more information about the [metrics section][11] and [metrics points array][12]. + +Visit Bonsai, the Sensu asset index, for more information about the [sensu/http-checks][7] dynamic runtime asset's capabilities. + + +[1]: ../checks/ +[2]: ../monitor-server-resources/ +[3]: https://assets.nagios.com/downloads/nagioscore/docs/nagioscore/3/en/perfdata.html +[4]: https://bonsai.sensu.io/assets/sensu/http-checks#http-perf +[5]: ../../observe-process/populate-metrics-influxdb/ +[6]: https://github.com/sensu/catalog/blob/docs-archive/integrations/influxdb/influxdb.yaml +[7]: https://bonsai.sensu.io/assets/sensu/http-checks +[8]: ../subscriptions/ +[9]: ../../../operations/monitoring-as-code/ +[10]: ../../../operations/maintain-sensu/troubleshoot/#use-a-debug-handler +[11]: ../../observe-events/events/#metrics-attribute +[12]: ../../observe-events/events/#metrics-points +[13]: ../../../operations/deploy-sensu/install-sensu/#install-the-sensu-backend +[14]: ../prometheus-metrics/ +[15]: ../../observe-process/pipelines/ +[16]: ../../../operations/deploy-sensu/install-sensu/#install-sensu-agents +[17]: ../../../operations/deploy-sensu/install-sensu/#install-sensuctl +[18]: ../../observe-process/handlers/ +[19]: ../../../plugins/assets/ +[20]: ../../observe-process/send-data-sumo-logic/ diff --git a/content/sensu-go/6.12/observability-pipeline/observe-schedule/hooks.md b/content/sensu-go/6.12/observability-pipeline/observe-schedule/hooks.md new file mode 100644 index 0000000000..88e958dac1 --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-schedule/hooks.md @@ -0,0 +1,510 @@ +--- +title: "Hooks reference" +linkTitle: "Hooks Reference" +reference_title: "Hooks" +type: "reference" +description: "Read this reference to free up precious operator time with hooks, which allow you to automate data collection that operators would typically perform manually." +weight: 40 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: observe-schedule +--- + +Hooks are reusable commands the agent executes in response to a check result before creating an observability event. +You can create, manage, and reuse hooks independently of checks. +Hooks enrich observability event context by gathering relevant information based on the exit status code of a check (ex: `1`). +Hook commands can also receive JSON serialized Sensu client data via stdin. + +## Hook example + +You can use hooks to automate data gathering for incident triage. +This example demonstrates a check hook to capture the process tree when a process is not running: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: HookConfig +api_version: core/v2 +metadata: + name: process_tree +spec: + command: ps aux + stdin: false + timeout: 60 + runtime_assets: null +{{< /code >}} + +{{< code json >}} +{ + "type": "HookConfig", + "api_version": "core/v2", + "metadata": { + "name": "process_tree" + }, + "spec": { + "command": "ps aux", + "timeout": 60, + "stdin": false, + "runtime_assets": null + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Check response types + +Each **type** of response (ex: `non-zero`) can contain one or more hooks and correspond to one or more exit status codes. +Hooks are executed in order of precedence, based on their type: + +1. `1` to `255` +2. `ok` +3. `warning` +4. `critical` +5. `unknown` +6. `non-zero` + +You can assign one or more hooks to a check in the check definition. +review the [check specification][6] to configure the `check_hooks` attribute. + +## Check hooks + +Sensu captures the hook command output, status, executed timestamp, and duration and publishes them in the resulting event. + +You can use `sensuctl` to view hook command data: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl event info --format yaml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl event info --format wrapped-json +{{< /code >}} + +{{< /language-toggle >}} + +The response lists the specified event, which includes the hook command data: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Event +api_version: core/v2 +metadata: + namespace: default +spec: + check: + ... + hooks: + - command: df -hT / | grep '/' + duration: 0.002904412 + executed: 1559948435 + issued: 0 + metadata: + name: root_disk + namespace: default + output: "/dev/mapper/centos-root xfs 41G 1.6G 40G 4% /\n" + status: 0 + stdin: false + timeout: 60 +{{< /code >}} + +{{< code json >}} +{ + "type": "Event", + "api_version": "core/v2", + "metadata": { + "namespace": "default" + }, + "spec": { + "check": { + "...": "...", + "hooks": [ + { + "command": "df -hT / | grep '/'", + "duration": 0.002904412, + "executed": 1559948435, + "issued": 0, + "metadata": { + "name": "root_disk", + "namespace": "default" + }, + "output": "/dev/mapper/centos-root xfs 41G 1.6G 40G 4% /\n", + "status": 0, + "stdin": false, + "timeout": 60 + } + ] + } + } +} +{{< /code >}} + +{{< /language-toggle >}} + +{{% notice protip %}} +**PRO TIP**: You can also [view complete resource definitions in the Sensu web UI](../../../web-ui/view-manage-resources/#view-resource-data-in-the-web-ui). +{{% /notice %}} + +## Hook specification + +### Top-level attributes + +api_version | +-------------|------ +description | Top-level attribute that specifies the Sensu API group and version. For hooks in this version of Sensu, the `api_version` should always be `core/v2`. +required | Required for hook definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][1]. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +api_version: core/v2 +{{< /code >}} +{{< code json >}} +{ + "api_version": "core/v2" +} +{{< /code >}} +{{< /language-toggle >}} + +metadata | +-------------|------ +description | Top-level collection of metadata about the hook that includes `name`, `namespace`, and `created_by` as well as custom `labels` and `annotations`. The `metadata` map is always at the top level of the hook definition. This means that in `wrapped-json` and `yaml` formats, the `metadata` scope occurs outside the `spec` scope. Read [metadata attributes][2] for details. +required | Required for hook definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][1]. +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +metadata: + name: process_tree + namespace: default + created_by: admin + labels: + region: us-west-1 + annotations: + slack-channel: "#monitoring" +{{< /code >}} +{{< code json >}} +{ + "metadata": { + "name": "process_tree", + "namespace": "default", + "created_by": "admin", + "labels": { + "region": "us-west-1" + }, + "annotations": { + "slack-channel": "#monitoring" + } + } +} +{{< /code >}} +{{< /language-toggle >}} + +spec | +-------------|------ +description | Top-level map that includes the hook [spec attributes][9]. +required | Required for hook definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][1]. +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +spec: + command: ps aux + timeout: 60 + stdin: false +{{< /code >}} +{{< code json >}} +{ + "spec": { + "command": "ps aux", + "timeout": 60, + "stdin": false + } +} +{{< /code >}} +{{< /language-toggle >}} + +type | +-------------|------ +description | Top-level attribute that specifies the [`sensuctl create`][1] resource type. Hooks should always be type `HookConfig`. +required | Required for hook definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][1]. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +type: HookConfig +{{< /code >}} +{{< code json >}} +{ + "type": "HookConfig" +} +{{< /code >}} +{{< /language-toggle >}} + +### Metadata attributes + +| annotations | | +-------------|------ +description | Non-identifying metadata to include with observation event data that you can access with [event filters][4]. You can use annotations to add data that's meaningful to people or external tools that interact with Sensu.

    In contrast to labels, you cannot use annotations in [API response filtering][10], [sensuctl response filtering][11], or [web UI views][13]. +required | false +type | Map of key-value pairs. Keys and values can be any valid UTF-8 string. +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +annotations: + managed-by: ops + playbook: www.example.url +{{< /code >}} +{{< code json >}} +{ + "annotations": { + "managed-by": "ops", + "playbook": "www.example.url" + } +} +{{< /code >}} +{{< /language-toggle >}} + +| created_by | | +-------------|------ +description | Username of the Sensu user who created the hook or last updated the hook. Sensu automatically populates the `created_by` field when the hook is created or updated. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +created_by: admin +{{< /code >}} +{{< code json >}} +{ + "created_by": "admin" +} +{{< /code >}} +{{< /language-toggle >}} + +| labels | | +-------------|------ +description | Custom attributes to include with observation event data that you can use for response and web UI view filtering.

    If you include labels in your event data, you can filter [API responses][10], [sensuctl responses][11], and [web UI views][12] based on them. In other words, labels allow you to create meaningful groupings for your data.

    Limit labels to metadata you need to use for response filtering. For complex, non-identifying metadata that you will *not* need to use in response filtering, use annotations rather than labels. +required | false +type | Map of key-value pairs. Keys can contain only letters, numbers, and underscores and must start with a letter. Values can be any valid UTF-8 string. +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +labels: + environment: development + region: us-west-2 +{{< /code >}} +{{< code json >}} +{ + "labels": { + "environment": "development", + "region": "us-west-2" + } +} +{{< /code >}} +{{< /language-toggle >}} + +| name | | +-------------|------ +description | Unique string used to identify the hook. Hook names cannot contain special characters or spaces (validated with Go regex [`\A[\w\.\-]+\z`][8]). Each hook must have a unique name within its namespace. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +name: process_tree +{{< /code >}} +{{< code json >}} +{ + "name": "process_tree" +} +{{< /code >}} +{{< /language-toggle >}} + +| namespace | | +-------------|------ +description | The Sensu [RBAC namespace][3] that this hook belongs to. +required | false +type | String +default | `default` +example | {{< language-toggle >}} +{{< code yml >}} +namespace: production +{{< /code >}} +{{< code json >}} +{ + "namespace": "production" +} +{{< /code >}} +{{< /language-toggle >}} + +### Spec attributes + +command | +-------------|------ +description | Hook command to be executed. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +command: sudo /etc/init.d/nginx start +{{< /code >}} +{{< code json >}} +{ + "command": "sudo /etc/init.d/nginx start" +} +{{< /code >}} +{{< /language-toggle >}} + +|runtime_assets | | +-------------|------ +description | Array of [Sensu dynamic runtime assets][5] (by their names) required at runtime for execution of the `command`. +required | false +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +runtime_assets: +- log-context +{{< /code >}} +{{< code json >}} +{ + "runtime_assets": [ + "log-context" + ] +} +{{< /code >}} +{{< /language-toggle >}} + +stdin | +-------------|------ +description | If `true`, the Sensu agent writes JSON serialized Sensu entity and check data to the command process stdin. Otherwise, `false`. The command must expect the JSON data via stdin, read it, and close stdin. This attribute cannot be used with existing Sensu check plugins or Nagios plugins because the Sensu agent will wait indefinitely for the hook process to read and close stdin. +required | false +type | Boolean +default | `false` +example | {{< language-toggle >}} +{{< code yml >}} +stdin: true +{{< /code >}} +{{< code json >}} +{ + "stdin": true +} +{{< /code >}} +{{< /language-toggle >}} + +timeout | +-------------|------ +description | Hook execution duration timeout (hard stop). In seconds. +required | false +type | Integer +default | 60 +example | {{< language-toggle >}} +{{< code yml >}} +timeout: 30 +{{< /code >}} +{{< code json >}} +{ + "timeout": 30 +} +{{< /code >}} +{{< /language-toggle >}} + +## Hook for rudimentary auto-remediation + +You can use hooks for rudimentary auto-remediation tasks, such as starting a process that is no longer running. + +{{% notice note %}} +**NOTE**: Use caution with this approach. Hooks used for auto-remediation will run without regard to the number of event occurrences. +{{% /notice %}} + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: HookConfig +api_version: core/v2 +metadata: + name: restart_nginx +spec: + command: sudo systemctl start nginx + stdin: false + timeout: 60 +{{< /code >}} + +{{< code json >}} +{ + "type": "HookConfig", + "api_version": "core/v2", + "metadata": { + "name": "restart_nginx" + }, + "spec": { + "command": "sudo systemctl start nginx", + "timeout": 60, + "stdin": false + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Hook that uses token substitution + +You can create check hooks that use [token substitution][7] so you can fine-tune check attributes on a per-entity level and re-use the check definition. + +{{% notice note %}} +**NOTE**: Token substitution uses entity-scoped metadata, so make sure to set labels at the entity level. +{{% /notice %}} + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: HookConfig +api_version: core/v2 +metadata: + labels: + foo: bar + name: tokensub +spec: + command: tokensub {{ .labels.foo }} + stdin: false + timeout: 60 +{{< /code >}} + +{{< code json >}} +{ + "type": "HookConfig", + "api_version": "core/v2", + "metadata": { + "labels": { + "foo": "bar" + }, + "name": "tokensub" + }, + "spec": { + "command": "tokensub {{ .labels.foo }}", + "stdin": false, + "timeout": 60 + } +} +{{< /code >}} + +{{< /language-toggle >}} + + +[1]: ../../../sensuctl/create-manage-resources/#create-resources +[2]: #metadata-attributes +[3]: ../../../operations/control-access/namespaces/ +[4]: ../../observe-filter/filters/ +[5]: ../../../plugins/assets/ +[6]: ../checks#check-hooks-attribute +[7]: ../tokens/ +[8]: https://regex101.com/r/zo9mQU/2 +[9]: #spec-attributes +[10]: ../../../api/#response-filtering +[11]: ../../../sensuctl/filter-responses/ +[12]: ../../../web-ui/search#search-for-labels +[13]: ../../../web-ui/search diff --git a/content/sensu-go/6.12/observability-pipeline/observe-schedule/metrics.md b/content/sensu-go/6.12/observability-pipeline/observe-schedule/metrics.md new file mode 100644 index 0000000000..7e801071d0 --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-schedule/metrics.md @@ -0,0 +1,1455 @@ +--- +title: "Metrics reference" +linkTitle: "Metrics Reference" +reference_title: "Metrics" +type: "reference" +description: "Read this reference to collect service and time-series metrics for your infrastructure and process extracted metrics with the Sensu observability pipeline." +weight: 50 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: observe-schedule +--- + +Sensu Go offers built-in support for collecting and processing service and time-series metrics for your entire infrastructure. + +In Sensu, metrics are an optional component of observation data in events. +Sensu events may contain check execution results, metrics, or both. +Certain inputs like the [Sensu StatsD listener][2] or patterns like the [Prometheus][7] collector pattern will create metrics-only events. +Events can also include metrics from [check output metric extraction][4]. + +Use Sensu handlers to [process extracted metrics][11] and route them to databases like Elasticsearch, InfluxDB, Grafana, and Graphite. +You can also use Sensu's [time-series and long-term event storage integrations][18] to process service and time-series metrics. + +{{% notice note %}} +**NOTE**: This reference describes the metrics component of observation data included in Sensu events, which is distinct from the Sensu /metrics API. +For information about HTTP GET access to internal Sensu metrics, read our [/metrics API](../../../api/other/metrics/) documentation. +{{% /notice %}} + +## Metric check example + +This check definition collects metrics in Graphite Plaintext Protocol [format][9] using the [sensu/system-check][26] dynamic runtime asset and sends the collected metrics to a pipeline configured with handlers that use the [sensu/sensu-go-graphite-handler][12] dynamic runtime asset: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: collect-system-metrics +spec: + check_hooks: null + command: system-check + env_vars: null + high_flap_threshold: 0 + interval: 10 + low_flap_threshold: 0 + output_metric_format: graphite_plaintext + pipelines: + - type: Pipeline + api_version: core/v2 + name: graphite_workflows + proxy_entity_name: "" + publish: true + round_robin: false + runtime_assets: + - system-check + secrets: null + stdin: false + subdue: null + subscriptions: + - system + timeout: 0 + ttl: 0 +{{< /code >}} + +{{< code json >}} +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "collect-system-metrics" + }, + "spec": { + "check_hooks": null, + "command": "system-check", + "env_vars": null, + "high_flap_threshold": 0, + "interval": 10, + "low_flap_threshold": 0, + "output_metric_format": "graphite_plaintext", + "pipelines": [ + { + "type": "Pipeline", + "api_version": "core/v2", + "name": "graphite_workflows" + } + ], + "proxy_entity_name": "", + "publish": true, + "round_robin": false, + "runtime_assets": [ + "system-check" + ], + "secrets": null, + "stdin": false, + "subdue": null, + "subscriptions": [ + "system" + ], + "timeout": 0, + "ttl": 0 + } +} +{{< /code >}} + +{{< /language-toggle >}} + +### Metric event example + +The [example metric check][6] will produce events similar to this metric event: + +{{< language-toggle >}} + +{{< code yml >}} +--- +pipelines: +- type: Pipeline + api_version: core/v2 + name: graphite_workflows +timestamp: 1635270402 +entity: + entity_class: agent + system: + hostname: sensu-centos + os: linux + platform: centos + platform_family: rhel + platform_version: 7.5.1804 + network: + interfaces: + - name: lo + addresses: + - 127.0.0.1/8 + - "::1/128" + - name: eth0 + mac: '08:00:27:8b:c9:3f' + addresses: + - 10.0.2.15/24 + - fe80::7103:bbce:3543:cfcf/64 + - name: eth1 + mac: '08:00:27:36:bb:67' + addresses: + - 172.28.128.89/24 + - fe80::a00:27ff:fe36:bb67/64 + arch: amd64 + libc_type: glibc + vm_system: vbox + vm_role: guest + cloud_provider: '' + processes: + subscriptions: + - system + - entity:sensu-centos + last_seen: 1635270399 + deregister: false + deregistration: {} + user: agent + redact: + - password + - passwd + - pass + - api_key + - api_token + - access_key + - secret_key + - private_key + - secret + metadata: + name: sensu-centos + namespace: default + sensu_agent_version: 6.5.1 +check: + command: system-check + high_flap_threshold: 0 + interval: 10 + low_flap_threshold: 0 + publish: true + runtime_assets: + - system-check + subscriptions: + - system + proxy_entity_name: '' + check_hooks: + stdin: false + subdue: + ttl: 0 + timeout: 0 + round_robin: false + duration: 3.00889206 + executed: 1635270399 + history: + - status: 0 + executed: 1635270359 + - status: 0 + executed: 1635270369 + - status: 0 + executed: 1635270379 + - status: 0 + executed: 1635270389 + - status: 0 + executed: 1635270399 + issued: 1635270399 + output: |+ + # HELP system_cpu_cores [GAUGE] Number of cpu cores on the system + # TYPE system_cpu_cores GAUGE + system_cpu_cores{} 1 1635270399219 + # HELP system_cpu_idle [GAUGE] Percent of time all cpus were idle + # TYPE system_cpu_idle GAUGE + system_cpu_idle{cpu="cpu0"} 99.32885906040329 1635270399219 + system_cpu_idle{cpu="cpu-total"} 99.32885906040329 1635270399219 + # HELP system_cpu_used [GAUGE] Percent of time all cpus were used + # TYPE system_cpu_used GAUGE + system_cpu_used{cpu="cpu0"} 0.671140939596711 1635270399219 + system_cpu_used{cpu="cpu-total"} 0.671140939596711 1635270399219 + # HELP system_cpu_user [GAUGE] Percent of time total cpu was used by normal processes in user mode + # TYPE system_cpu_user GAUGE + system_cpu_user{cpu="cpu0"} 0.3355704697986485 1635270399219 + system_cpu_user{cpu="cpu-total"} 0.3355704697986485 1635270399219 + # HELP system_cpu_system [GAUGE] Percent of time all cpus used by processes executed in kernel mode + # TYPE system_cpu_system GAUGE + system_cpu_system{cpu="cpu0"} 0.33557046979867833 1635270399219 + system_cpu_system{cpu="cpu-total"} 0.33557046979867833 1635270399219 + # HELP system_cpu_nice [GAUGE] Percent of time all cpus used by niced processes in user mode + # TYPE system_cpu_nice GAUGE + system_cpu_nice{cpu="cpu0"} 0 1635270399219 + system_cpu_nice{cpu="cpu-total"} 0 1635270399219 + # HELP system_cpu_iowait [GAUGE] Percent of time all cpus waiting for I/O to complete + # TYPE system_cpu_iowait GAUGE + system_cpu_iowait{cpu="cpu0"} 0 1635270399219 + system_cpu_iowait{cpu="cpu-total"} 0 1635270399219 + # HELP system_cpu_irq [GAUGE] Percent of time all cpus servicing interrupts + # TYPE system_cpu_irq GAUGE + system_cpu_irq{cpu="cpu0"} 0 1635270399219 + system_cpu_irq{cpu="cpu-total"} 0 1635270399219 + # HELP system_cpu_sortirq [GAUGE] Percent of time all cpus servicing software interrupts + # TYPE system_cpu_sortirq GAUGE + system_cpu_sortirq{cpu="cpu0"} 0 1635270399219 + system_cpu_sortirq{cpu="cpu-total"} 0 1635270399219 + # HELP system_cpu_stolen [GAUGE] Percent of time all cpus serviced virtual hosts operating systems + # TYPE system_cpu_stolen GAUGE + system_cpu_stolen{cpu="cpu0"} 0 1635270399219 + system_cpu_stolen{cpu="cpu-total"} 0 1635270399219 + # HELP system_cpu_guest [GAUGE] Percent of time all cpus serviced guest operating system + # TYPE system_cpu_guest GAUGE + system_cpu_guest{cpu="cpu0"} 0 1635270399219 + system_cpu_guest{cpu="cpu-total"} 0 1635270399219 + # HELP system_cpu_guest_nice [GAUGE] Percent of time all cpus serviced niced guest operating system + # TYPE system_cpu_guest_nice GAUGE + system_cpu_guest_nice{cpu="cpu0"} 0 1635270399219 + system_cpu_guest_nice{cpu="cpu-total"} 0 1635270399219 + # HELP system_mem_used [GAUGE] Percent of memory used + # TYPE system_mem_used GAUGE + system_mem_used{} 21.21448463577672 1635270399219 + # HELP system_mem_used_bytes [GAUGE] Used memory in bytes + # TYPE system_mem_used_bytes GAUGE + system_mem_used_bytes{} 2.20598272e+08 1635270399219 + # HELP system_mem_total_bytes [GAUGE] Total memory in bytes + # TYPE system_mem_total_bytes GAUGE + system_mem_total_bytes{} 1.039847424e+09 1635270399219 + # HELP system_swap_used [GAUGE] Percent of swap used + # TYPE system_swap_used GAUGE + system_swap_used{} 0 1635270399219 + # HELP system_swap_used_bytes [GAUGE] Used swap in bytes + # TYPE system_swap_used_bytes GAUGE + system_swap_used_bytes{} 2.20598272e+08 1635270399219 + # HELP system_swap_total_bytes [GAUGE] Total swap in bytes + # TYPE system_swap_total_bytes GAUGE + system_swap_total_bytes{} 2.147479552e+09 1635270399219 + # HELP system_load_load1 [GAUGE] System load averaged over 1 minute, high load value dependant on number of cpus in system + # TYPE system_load_load1 GAUGE + system_load_load1{} 0 1635270399219 + # HELP system_load_load5 [GAUGE] System load averaged over 5 minute, high load value dependent on number of cpus in system + # TYPE system_load_load5 GAUGE + system_load_load5{} 0.01 1635270399219 + # HELP system_load_load15 [GAUGE] System load averaged over 15 minute, high load value dependent on number of cpus in system + # TYPE system_load_load15 GAUGE + system_load_load15{} 0.05 1635270399219 + # HELP system_load_load1_per_cpu [GAUGE] System load averaged over 1 minute normalized by cpu count, values \u003e 1 means system may be overloaded + # TYPE system_load_load1_per_cpu GAUGE + system_load_load1_per_cpu{} 0 1635270399219 + # HELP system_load_load5_per_cpu [GAUGE] System load averaged over 5 minute normalized by cpu count, values \u003e 1 means system may be overloaded + # TYPE system_load_load5_per_cpu GAUGE + system_load_load5_per_cpu{} 0.01 1635270399219 + # HELP system_load_load15_per_cpu [GAUGE] System load averaged over 15 minute normalized by cpu count, values \u003e 1 means system may be overloaded + # TYPE system_load_load15_per_cpu GAUGE + system_load_load15_per_cpu{} 0.05 1635270399219 + # HELP system_host_uptime [COUNTER] Host uptime in seconds + # TYPE system_host_uptime COUNTER + system_host_uptime{} 982 1635270399219 + # HELP system_host_processes [GAUGE] Number of host processes + # TYPE system_host_processes GAUGE + system_host_processes{} 109 1635270399219 + state: passing + status: 0 + total_state_change: 0 + last_ok: 1635270399 + occurrences: 5 + occurrences_watermark: 5 + output_metric_format: graphite_plaintext + env_vars: + metadata: + name: collect-system-metrics + namespace: default + secrets: + is_silenced: false + scheduler: memory + processed_by: sensu-centos +metrics: + points: + - name: system_cpu_cores{} + value: 1 + timestamp: 1635270399219 + tags: + - name: system_cpu_idle{cpu="cpu0"} + value: 99.32885906040329 + timestamp: 1635270399219 + tags: + - name: system_cpu_idle{cpu="cpu-total"} + value: 99.32885906040329 + timestamp: 1635270399219 + tags: + - name: system_cpu_used{cpu="cpu0"} + value: 0.671140939596711 + timestamp: 1635270399219 + tags: + - name: system_cpu_used{cpu="cpu-total"} + value: 0.671140939596711 + timestamp: 1635270399219 + tags: + - name: system_cpu_user{cpu="cpu0"} + value: 0.3355704697986485 + timestamp: 1635270399219 + tags: + - name: system_cpu_user{cpu="cpu-total"} + value: 0.3355704697986485 + timestamp: 1635270399219 + tags: + - name: system_cpu_system{cpu="cpu0"} + value: 0.33557046979867833 + timestamp: 1635270399219 + tags: + - name: system_cpu_system{cpu="cpu-total"} + value: 0.33557046979867833 + timestamp: 1635270399219 + tags: + - name: system_cpu_nice{cpu="cpu0"} + value: 0 + timestamp: 1635270399219 + tags: + - name: system_cpu_nice{cpu="cpu-total"} + value: 0 + timestamp: 1635270399219 + tags: + - name: system_cpu_iowait{cpu="cpu0"} + value: 0 + timestamp: 1635270399219 + tags: + - name: system_cpu_iowait{cpu="cpu-total"} + value: 0 + timestamp: 1635270399219 + tags: + - name: system_cpu_irq{cpu="cpu0"} + value: 0 + timestamp: 1635270399219 + tags: + - name: system_cpu_irq{cpu="cpu-total"} + value: 0 + timestamp: 1635270399219 + tags: + - name: system_cpu_sortirq{cpu="cpu0"} + value: 0 + timestamp: 1635270399219 + tags: + - name: system_cpu_sortirq{cpu="cpu-total"} + value: 0 + timestamp: 1635270399219 + tags: + - name: system_cpu_stolen{cpu="cpu0"} + value: 0 + timestamp: 1635270399219 + tags: + - name: system_cpu_stolen{cpu="cpu-total"} + value: 0 + timestamp: 1635270399219 + tags: + - name: system_cpu_guest{cpu="cpu0"} + value: 0 + timestamp: 1635270399219 + tags: + - name: system_cpu_guest{cpu="cpu-total"} + value: 0 + timestamp: 1635270399219 + tags: + - name: system_cpu_guest_nice{cpu="cpu0"} + value: 0 + timestamp: 1635270399219 + tags: + - name: system_cpu_guest_nice{cpu="cpu-total"} + value: 0 + timestamp: 1635270399219 + tags: + - name: system_mem_used{} + value: 21.21448463577672 + timestamp: 1635270399219 + tags: + - name: system_mem_used_bytes{} + value: 220598272 + timestamp: 1635270399219 + tags: + - name: system_mem_total_bytes{} + value: 1039847424 + timestamp: 1635270399219 + tags: + - name: system_swap_used{} + value: 0 + timestamp: 1635270399219 + tags: + - name: system_swap_used_bytes{} + value: 220598272 + timestamp: 1635270399219 + tags: + - name: system_swap_total_bytes{} + value: 2147479552 + timestamp: 1635270399219 + tags: + - name: system_load_load1{} + value: 0 + timestamp: 1635270399219 + tags: + - name: system_load_load5{} + value: 0.01 + timestamp: 1635270399219 + tags: + - name: system_load_load15{} + value: 0.05 + timestamp: 1635270399219 + tags: + - name: system_load_load1_per_cpu{} + value: 0 + timestamp: 1635270399219 + tags: + - name: system_load_load5_per_cpu{} + value: 0.01 + timestamp: 1635270399219 + tags: + - name: system_load_load15_per_cpu{} + value: 0.05 + timestamp: 1635270399219 + tags: + - name: system_host_uptime{} + value: 982 + timestamp: 1635270399219 + tags: + - name: system_host_processes{} + value: 109 + timestamp: 1635270399219 + tags: +metadata: + namespace: default +id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx +sequence: 5 +{{< /code >}} + +{{< code json >}} +{ + "pipelines": [ + { + "type": "Pipeline", + "api_version": "core/v2", + "name": "graphite_workflows" + } + ], + "timestamp": 1635270402, + "entity": { + "entity_class": "agent", + "system": { + "hostname": "sensu-centos", + "os": "linux", + "platform": "centos", + "platform_family": "rhel", + "platform_version": "7.5.1804", + "network": { + "interfaces": [ + { + "name": "lo", + "addresses": [ + "127.0.0.1/8", + "::1/128" + ] + }, + { + "name": "eth0", + "mac": "08:00:27:8b:c9:3f", + "addresses": [ + "10.0.2.15/24", + "fe80::7103:bbce:3543:cfcf/64" + ] + }, + { + "name": "eth1", + "mac": "08:00:27:36:bb:67", + "addresses": [ + "172.28.128.89/24", + "fe80::a00:27ff:fe36:bb67/64" + ] + } + ] + }, + "arch": "amd64", + "libc_type": "glibc", + "vm_system": "vbox", + "vm_role": "guest", + "cloud_provider": "", + "processes": null + }, + "subscriptions": [ + "system", + "entity:sensu-centos" + ], + "last_seen": 1635270399, + "deregister": false, + "deregistration": {}, + "user": "agent", + "redact": [ + "password", + "passwd", + "pass", + "api_key", + "api_token", + "access_key", + "secret_key", + "private_key", + "secret" + ], + "metadata": { + "name": "sensu-centos", + "namespace": "default" + }, + "sensu_agent_version": "6.5.1" + }, + "check": { + "command": "system-check", + "high_flap_threshold": 0, + "interval": 10, + "low_flap_threshold": 0, + "publish": true, + "runtime_assets": [ + "system-check" + ], + "subscriptions": [ + "system" + ], + "proxy_entity_name": "", + "check_hooks": null, + "stdin": false, + "subdue": null, + "ttl": 0, + "timeout": 0, + "round_robin": false, + "duration": 3.00889206, + "executed": 1635270399, + "history": [ + { + "status": 0, + "executed": 1635270359 + }, + { + "status": 0, + "executed": 1635270369 + }, + { + "status": 0, + "executed": 1635270379 + }, + { + "status": 0, + "executed": 1635270389 + }, + { + "status": 0, + "executed": 1635270399 + } + ], + "issued": 1635270399, + "output": "# HELP system_cpu_cores [GAUGE] Number of cpu cores on the system\n# TYPE system_cpu_cores GAUGE\nsystem_cpu_cores{} 1 1635270399219\n# HELP system_cpu_idle [GAUGE] Percent of time all cpus were idle\n# TYPE system_cpu_idle GAUGE\nsystem_cpu_idle{cpu=\"cpu0\"} 99.32885906040329 1635270399219\nsystem_cpu_idle{cpu=\"cpu-total\"} 99.32885906040329 1635270399219\n# HELP system_cpu_used [GAUGE] Percent of time all cpus were used\n# TYPE system_cpu_used GAUGE\nsystem_cpu_used{cpu=\"cpu0\"} 0.671140939596711 1635270399219\nsystem_cpu_used{cpu=\"cpu-total\"} 0.671140939596711 1635270399219\n# HELP system_cpu_user [GAUGE] Percent of time total cpu was used by normal processes in user mode\n# TYPE system_cpu_user GAUGE\nsystem_cpu_user{cpu=\"cpu0\"} 0.3355704697986485 1635270399219\nsystem_cpu_user{cpu=\"cpu-total\"} 0.3355704697986485 1635270399219\n# HELP system_cpu_system [GAUGE] Percent of time all cpus used by processes executed in kernel mode\n# TYPE system_cpu_system GAUGE\nsystem_cpu_system{cpu=\"cpu0\"} 0.33557046979867833 1635270399219\nsystem_cpu_system{cpu=\"cpu-total\"} 0.33557046979867833 1635270399219\n# HELP system_cpu_nice [GAUGE] Percent of time all cpus used by niced processes in user mode\n# TYPE system_cpu_nice GAUGE\nsystem_cpu_nice{cpu=\"cpu0\"} 0 1635270399219\nsystem_cpu_nice{cpu=\"cpu-total\"} 0 1635270399219\n# HELP system_cpu_iowait [GAUGE] Percent of time all cpus waiting for I/O to complete\n# TYPE system_cpu_iowait GAUGE\nsystem_cpu_iowait{cpu=\"cpu0\"} 0 1635270399219\nsystem_cpu_iowait{cpu=\"cpu-total\"} 0 1635270399219\n# HELP system_cpu_irq [GAUGE] Percent of time all cpus servicing interrupts\n# TYPE system_cpu_irq GAUGE\nsystem_cpu_irq{cpu=\"cpu0\"} 0 1635270399219\nsystem_cpu_irq{cpu=\"cpu-total\"} 0 1635270399219\n# HELP system_cpu_sortirq [GAUGE] Percent of time all cpus servicing software interrupts\n# TYPE system_cpu_sortirq GAUGE\nsystem_cpu_sortirq{cpu=\"cpu0\"} 0 1635270399219\nsystem_cpu_sortirq{cpu=\"cpu-total\"} 0 1635270399219\n# HELP system_cpu_stolen [GAUGE] Percent of time all cpus serviced virtual hosts operating systems\n# TYPE system_cpu_stolen GAUGE\nsystem_cpu_stolen{cpu=\"cpu0\"} 0 1635270399219\nsystem_cpu_stolen{cpu=\"cpu-total\"} 0 1635270399219\n# HELP system_cpu_guest [GAUGE] Percent of time all cpus serviced guest operating system\n# TYPE system_cpu_guest GAUGE\nsystem_cpu_guest{cpu=\"cpu0\"} 0 1635270399219\nsystem_cpu_guest{cpu=\"cpu-total\"} 0 1635270399219\n# HELP system_cpu_guest_nice [GAUGE] Percent of time all cpus serviced niced guest operating system\n# TYPE system_cpu_guest_nice GAUGE\nsystem_cpu_guest_nice{cpu=\"cpu0\"} 0 1635270399219\nsystem_cpu_guest_nice{cpu=\"cpu-total\"} 0 1635270399219\n# HELP system_mem_used [GAUGE] Percent of memory used\n# TYPE system_mem_used GAUGE\nsystem_mem_used{} 21.21448463577672 1635270399219\n# HELP system_mem_used_bytes [GAUGE] Used memory in bytes\n# TYPE system_mem_used_bytes GAUGE\nsystem_mem_used_bytes{} 2.20598272e+08 1635270399219\n# HELP system_mem_total_bytes [GAUGE] Total memory in bytes\n# TYPE system_mem_total_bytes GAUGE\nsystem_mem_total_bytes{} 1.039847424e+09 1635270399219\n# HELP system_swap_used [GAUGE] Percent of swap used\n# TYPE system_swap_used GAUGE\nsystem_swap_used{} 0 1635270399219\n# HELP system_swap_used_bytes [GAUGE] Used swap in bytes\n# TYPE system_swap_used_bytes GAUGE\nsystem_swap_used_bytes{} 2.20598272e+08 1635270399219\n# HELP system_swap_total_bytes [GAUGE] Total swap in bytes\n# TYPE system_swap_total_bytes GAUGE\nsystem_swap_total_bytes{} 2.147479552e+09 1635270399219\n# HELP system_load_load1 [GAUGE] System load averaged over 1 minute, high load value dependant on number of cpus in system\n# TYPE system_load_load1 GAUGE\nsystem_load_load1{} 0 1635270399219\n# HELP system_load_load5 [GAUGE] System load averaged over 5 minute, high load value dependent on number of cpus in system\n# TYPE system_load_load5 GAUGE\nsystem_load_load5{} 0.01 1635270399219\n# HELP system_load_load15 [GAUGE] System load averaged over 15 minute, high load value dependent on number of cpus in system\n# TYPE system_load_load15 GAUGE\nsystem_load_load15{} 0.05 1635270399219\n# HELP system_load_load1_per_cpu [GAUGE] System load averaged over 1 minute normalized by cpu count, values \\u003e 1 means system may be overloaded\n# TYPE system_load_load1_per_cpu GAUGE\nsystem_load_load1_per_cpu{} 0 1635270399219\n# HELP system_load_load5_per_cpu [GAUGE] System load averaged over 5 minute normalized by cpu count, values \\u003e 1 means system may be overloaded\n# TYPE system_load_load5_per_cpu GAUGE\nsystem_load_load5_per_cpu{} 0.01 1635270399219\n# HELP system_load_load15_per_cpu [GAUGE] System load averaged over 15 minute normalized by cpu count, values \\u003e 1 means system may be overloaded\n# TYPE system_load_load15_per_cpu GAUGE\nsystem_load_load15_per_cpu{} 0.05 1635270399219\n# HELP system_host_uptime [COUNTER] Host uptime in seconds\n# TYPE system_host_uptime COUNTER\nsystem_host_uptime{} 982 1635270399219\n# HELP system_host_processes [GAUGE] Number of host processes\n# TYPE system_host_processes GAUGE\nsystem_host_processes{} 109 1635270399219\n", + "state": "passing", + "status": 0, + "total_state_change": 0, + "last_ok": 1635270399, + "occurrences": 5, + "occurrences_watermark": 5, + "output_metric_format": "graphite_plaintext", + "env_vars": null, + "metadata": { + "name": "collect-system-metrics", + "namespace": "default" + }, + "secrets": null, + "is_silenced": false, + "scheduler": "memory", + "processed_by": "sensu-centos" + }, + "metrics": { + "points": [ + { + "name": "system_cpu_cores{}", + "value": 1, + "timestamp": 1635270399219, + "tags": null + }, + { + "name": "system_cpu_idle{cpu=\"cpu0\"}", + "value": 99.32885906040329, + "timestamp": 1635270399219, + "tags": null + }, + { + "name": "system_cpu_idle{cpu=\"cpu-total\"}", + "value": 99.32885906040329, + "timestamp": 1635270399219, + "tags": null + }, + { + "name": "system_cpu_used{cpu=\"cpu0\"}", + "value": 0.671140939596711, + "timestamp": 1635270399219, + "tags": null + }, + { + "name": "system_cpu_used{cpu=\"cpu-total\"}", + "value": 0.671140939596711, + "timestamp": 1635270399219, + "tags": null + }, + { + "name": "system_cpu_user{cpu=\"cpu0\"}", + "value": 0.3355704697986485, + "timestamp": 1635270399219, + "tags": null + }, + { + "name": "system_cpu_user{cpu=\"cpu-total\"}", + "value": 0.3355704697986485, + "timestamp": 1635270399219, + "tags": null + }, + { + "name": "system_cpu_system{cpu=\"cpu0\"}", + "value": 0.33557046979867833, + "timestamp": 1635270399219, + "tags": null + }, + { + "name": "system_cpu_system{cpu=\"cpu-total\"}", + "value": 0.33557046979867833, + "timestamp": 1635270399219, + "tags": null + }, + { + "name": "system_cpu_nice{cpu=\"cpu0\"}", + "value": 0, + "timestamp": 1635270399219, + "tags": null + }, + { + "name": "system_cpu_nice{cpu=\"cpu-total\"}", + "value": 0, + "timestamp": 1635270399219, + "tags": null + }, + { + "name": "system_cpu_iowait{cpu=\"cpu0\"}", + "value": 0, + "timestamp": 1635270399219, + "tags": null + }, + { + "name": "system_cpu_iowait{cpu=\"cpu-total\"}", + "value": 0, + "timestamp": 1635270399219, + "tags": null + }, + { + "name": "system_cpu_irq{cpu=\"cpu0\"}", + "value": 0, + "timestamp": 1635270399219, + "tags": null + }, + { + "name": "system_cpu_irq{cpu=\"cpu-total\"}", + "value": 0, + "timestamp": 1635270399219, + "tags": null + }, + { + "name": "system_cpu_sortirq{cpu=\"cpu0\"}", + "value": 0, + "timestamp": 1635270399219, + "tags": null + }, + { + "name": "system_cpu_sortirq{cpu=\"cpu-total\"}", + "value": 0, + "timestamp": 1635270399219, + "tags": null + }, + { + "name": "system_cpu_stolen{cpu=\"cpu0\"}", + "value": 0, + "timestamp": 1635270399219, + "tags": null + }, + { + "name": "system_cpu_stolen{cpu=\"cpu-total\"}", + "value": 0, + "timestamp": 1635270399219, + "tags": null + }, + { + "name": "system_cpu_guest{cpu=\"cpu0\"}", + "value": 0, + "timestamp": 1635270399219, + "tags": null + }, + { + "name": "system_cpu_guest{cpu=\"cpu-total\"}", + "value": 0, + "timestamp": 1635270399219, + "tags": null + }, + { + "name": "system_cpu_guest_nice{cpu=\"cpu0\"}", + "value": 0, + "timestamp": 1635270399219, + "tags": null + }, + { + "name": "system_cpu_guest_nice{cpu=\"cpu-total\"}", + "value": 0, + "timestamp": 1635270399219, + "tags": null + }, + { + "name": "system_mem_used{}", + "value": 21.21448463577672, + "timestamp": 1635270399219, + "tags": null + }, + { + "name": "system_mem_used_bytes{}", + "value": 220598272, + "timestamp": 1635270399219, + "tags": null + }, + { + "name": "system_mem_total_bytes{}", + "value": 1039847424, + "timestamp": 1635270399219, + "tags": null + }, + { + "name": "system_swap_used{}", + "value": 0, + "timestamp": 1635270399219, + "tags": null + }, + { + "name": "system_swap_used_bytes{}", + "value": 220598272, + "timestamp": 1635270399219, + "tags": null + }, + { + "name": "system_swap_total_bytes{}", + "value": 2147479552, + "timestamp": 1635270399219, + "tags": null + }, + { + "name": "system_load_load1{}", + "value": 0, + "timestamp": 1635270399219, + "tags": null + }, + { + "name": "system_load_load5{}", + "value": 0.01, + "timestamp": 1635270399219, + "tags": null + }, + { + "name": "system_load_load15{}", + "value": 0.05, + "timestamp": 1635270399219, + "tags": null + }, + { + "name": "system_load_load1_per_cpu{}", + "value": 0, + "timestamp": 1635270399219, + "tags": null + }, + { + "name": "system_load_load5_per_cpu{}", + "value": 0.01, + "timestamp": 1635270399219, + "tags": null + }, + { + "name": "system_load_load15_per_cpu{}", + "value": 0.05, + "timestamp": 1635270399219, + "tags": null + }, + { + "name": "system_host_uptime{}", + "value": 982, + "timestamp": 1635270399219, + "tags": null + }, + { + "name": "system_host_processes{}", + "value": 109, + "timestamp": 1635270399219, + "tags": null + } + ] + }, + "metadata": { + "namespace": "default" + }, + "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "sequence": 5 +} +{{< /code >}} + +{{< /language-toggle >}} + +{{% notice note %}} +**NOTE**: Metrics data points are not included in events retrieved with `sensuctl event info` — these events include check output text rather than a set of metrics points. +To view metrics points data, add a [debug handler](../../../operations/maintain-sensu/troubleshoot#use-a-debug-handler) that prints events to a JSON file. +{{% /notice %}} + +## Extract metrics from check output + +The Sensu agent can extract metrics data from check command output and populate an event's [metrics attribute][5] before sending the event to the Sensu backend for [processing][11]. + +To extract metrics from check output: + +- The check `command` execution must output metrics in one of Sensu's [supported output metric formats][9]. +- The check must include the [`output_metric_format` attribute][10] with a value that specifies one of Sensu's [supported output metric formats][9]. + +When a check includes correctly configured `command` and `output_metric_format` attributes, Sensu will extract the specified metrics from the check output and add them to the event data in the [metrics attribute][5]. + +### Supported output metric formats + +Sensu supports the following formats for check output metric extraction. + +| Graphite | | +---------------------|------ +output metric format | `graphite_plaintext` +documentation | [Graphite Plaintext Protocol][14] +example | {{< code plain >}}local.random.diceroll 4 123456789{{< /code >}} + +| InfluxDB | | +---------------------|------ +output metric format | `influxdb_line` +documentation | [InfluxDB Line Protocol][15] +example | {{< code plain >}}weather,location=us-midwest temperature=82 1465839830100400200{{< /code >}} + +| Nagios | | +---------------------|------ +output metric format | `nagios_perfdata` +documentation | [Nagios Performance Data][13] +example | {{< code plain >}}PING ok - Packet loss = 0%, RTA = 0.80 ms | percent_packet_loss=0, rta=0.80{{< /code >}} + +| OpenTSDB | | +---------------------|------ +output metric format | `opentsdb_line` +documentation | [OpenTSDB Data Specification][16] +example | {{< code plain >}}sys.cpu.user 1356998400 42.5 host=webserver01 cpu=0{{< /code >}} + +| Prometheus | | +---------------------|------ +output metric format | `prometheus_text` +documentation | [Prometheus Exposition Text][17] +example | {{< code plain >}}http_requests_total{method="post",code="200"} 1027 1395066363000{{< /code >}} + +## Enrich metrics with tags + +In metric check output, metrics data [points][25] include the [`tags`][29] array. +Tags add information for the metrics points in [events][28]. +For example, a tag can specify the name of the check or entity associated with a specific metrics point. + +Tags can be generated in various ways, like [plugin][31] code or a third-party exporter. +You can also add specific tags to metrics points with output metric tags. + +### Add output metric tags + +[Output metric tags][1] are custom tags you can add to your check definition to enrich the metrics data points produced by check output metric extraction with additional context. + +The key-value pairs you add to a check's `output_metric_tags` array will be included in the `tags` array after check output metric extraction. +For example, suppose you include this `output_metric_tags` array in your check: + +{{< language-toggle >}} + +{{< code yml >}} +output_metric_tags: +- name: instance + value: sensu-centos-1 +- name: prometheus_type + value: gauge +{{< /code >}} + +{{< code json >}} +{ + "output_metric_tags": [ + { + "name": "instance", + "value": "sensu-centos-1" + }, + { + "name": "prometheus_type", + "value": "gauge" + } + ] +} +{{< /code >}} + +{{< /language-toggle >}} + +In check output, the metrics points would include the output metric tags in the `tags` array, similar to this example: + +{{< language-toggle >}} + +{{< code text "YML" >}} +points: +- name: dns_duration + value: 0.000251 + timestamp: 1648220984 + tags: + - name: instance + value: sensu-centos-1 + - name: prometheus_type + value: gauge +- name: tls_handshake_duration + value: 0 + timestamp: 1648220984 + tags: + - name: instance + value: sensu-centos-1 + - name: prometheus_type + value: gauge +{{< /code >}} + +{{< code text "JSON" >}} +{ + "points": [ + { + "name": "dns_duration", + "value": 0.000251, + "timestamp": 1648220984, + "tags": [ + { + "name": "instance", + "value": "sensu-centos-1" + }, + { + "name": "prometheus_type", + "value": "gauge" + } + ] + }, + { + "name": "tls_handshake_duration", + "value": 0, + "timestamp": 1648220984, + "tags": [ + { + "name": "instance", + "value": "sensu-centos-1" + }, + { + "name": "prometheus_type", + "value": "gauge" + } + ] + } + ] +} +{{< /code >}} + +{{< /language-toggle >}} + +Sensu adds any output metric tag values to the `tags` array along with any natively supported tags produced by check output metric extraction. + +### Use token substitution with output metric tags + +Use [token substitution][22] to include any [event attribute][30] in an output metric tag. +Add token substitution in the output metric tag `value` attribute. +For example, these tags will list the `event.timestamp` and `event.entity.name` attributes: + +{{< language-toggle >}} + +{{< code yml >}} +--- +output_metric_tags: +- name: time + value: "{{ .timestamp }}" +- name: entity_name + value: "{{ .entity.name }}" +{{< /code >}} + +{{< code json >}} +{ + "output_metric_tags": [ + { + "name": "time", + "value": "{{ .timestamp }}" + }, + { + "name": "entity_name", + "value": "{{ .entity.name }}" + } + ] +} +{{< /code >}} + +{{< /language-toggle >}} + +### Collect metrics in formats that do not support tags + +Output metric tags are useful when you want to collect metrics in a format that does not natively support tags, like Nagios Performance Data. + +For example, you might want to collect and transmit metrics in Nagios Performance Data format, which does not support tags, and store the metrics in Prometheus, which does support tags. +In this case, you can specify the tags to include with metrics with output metric tags. +The `output_metric_format`, `output_metric_handlers`, and `output_metric_tags` attributes in your check definition might look similar to this example: + +{{< language-toggle >}} + +{{< code yml >}} +output_metric_format: nagios_perfdata +output_metric_handlers: + - prometheus_gateway +output_metric_tags: + - name: instance + value: '{{ .name }}' + - name: prometheus_type + value: gauge + - name: service + value: '{{ .labels.service }}' +{{< /code >}} + +{{< code json >}} +{ + "output_metric_format": "nagios_perfdata", + "output_metric_handlers": [ + "prometheus_gateway" + ], + "output_metric_tags": [ + { + "name": "instance", + "value": "{{ .name }}" + }, + { + "name": "prometheus_type", + "value": "gauge" + }, + { + "name": "service", + "value": "{{ .labels.service }}" + } + ] +} +{{< /code >}} + +{{< /language-toggle >}} + +## Metric threshold evaluation + +Metric threshold evaluation extends Sensu's service check and metrics processing capabilities so you can get real-time alerts based on the metrics your Sensu checks collect. +The Sensu agent analyzes output metrics against the thresholds you specify and overrides the event [check status][36] if the metrics values exceed the threshold values. + +For example, the [check][34] from the Sensu Plus guide uses the [sensu/system-check][35] dynamic runtime asset to collect baseline system metrics. +Add the [`output_metric_thresholds`][33] array to get alerts based on the Sensu System Check metrics `system_mem_used` (percent of memory used) and `system_host_processes` (number of host processes): + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: system-check +spec: + command: system-check + runtime_assets: + - system-check + subscriptions: + - system + interval: 10 + timeout: 5 + publish: true + pipelines: + - type: Pipeline + api_version: core/v2 + name: sensu_to_sumo + output_metric_format: prometheus_text + output_metric_tags: + - name: entity + value: "{{ .name }}" + - name: namespace + value: "{{ .namespace }}" + - name: os + value: "{{ .system.os }}" + - name: platform + value: "{{ .system.platform }}" + output_metric_thresholds: + - name: system_mem_used + tags: + null_status: 1 + thresholds: + - max: '75.0' + min: '' + status: 1 + - max: '90.0' + min: '' + status: 2 + - name: system_host_processes + tags: + - name: namespace + value: production + null_status: 1 + thresholds: + - max: '50' + min: '5' + status: 1 + - max: '75' + min: '2' + status: 2 +{{< /code >}} + +{{< code json >}} +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "system-check" + }, + "spec": { + "command": "system-check", + "runtime_assets": [ + "system-check" + ], + "subscriptions": [ + "system" + ], + "interval": 10, + "timeout": 5, + "publish": true, + "pipelines": [ + { + "type": "Pipeline", + "api_version": "core/v2", + "name": "sensu_to_sumo" + } + ], + "output_metric_format": "prometheus_text", + "output_metric_tags": [ + { + "name": "entity", + "value": "{{ .name }}" + }, + { + "name": "namespace", + "value": "{{ .namespace }}" + }, + { + "name": "os", + "value": "{{ .system.os }}" + }, + { + "name": "platform", + "value": "{{ .system.platform }}" + } + ], + "output_metric_thresholds": [ + { + "name": "system_mem_used", + "tags": null, + "null_status": 1, + "thresholds": [ + { + "max": "75.0", + "min": "", + "status": 1 + }, + { + "max": "90.0", + "min": "", + "status": 2 + } + ] + }, + { + "name": "system_host_processes", + "tags": [ + { + "name": "namespace", + "value": "production" + } + ], + "null_status": 1, + "thresholds": [ + { + "max": "50", + "min": "5", + "status": 1 + }, + { + "max": "75", + "min": "2", + "status": 2 + } + ] + } + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +In this example, for both `system_mem_used` and `system_host_processes`, Sensu will compare the output metrics in each event with the thresholds set for each metric. +If the output metrics match or exceed the thresholds, Sensu will override the check status. + +For `system_mem_used`: +- Set event status to `1` (warning) if the output metrics do not include `system_mem_used`. +- Set event status to `1` (warning) when 75% of memory is used. +- Set event status to `2` (critical) when 90% of memory is used. + +For `system_host_processes`: +- Evaluate only output metrics for entities whose tags include `name: namespace` and `value: production`. +- Set event status to `1` (warning) if the output metrics do not include `system_host_processes`. +- Set event status to `1` (warning) when the number of host processes reaches 50 or more or 5 or fewer. +- Set event status to `2` (critical) when the number of host processes reaches 75 or more or 2 or fewer. + +{{% notice note %}} +**NOTE**: The Sensu Plus [example handler](../../../sensu-plus/#create-a-handler-in-sensu) processes and transmits metrics data but cannot send alerts. +Read [Send data to Sumo Logic with Sensu](../../observe-process/send-data-sumo-logic) to create a handler that sends alerts to Sumo Logic, which you can add to the Sensu Plus [example pipeline](../../../sensu-plus/#configure-a-pipeline). +{{% /notice %}} + +Metric threshold evaluation takes place *after* Sensu extracts metrics and *before* Sensu processes any check hooks. +If you specify a metric name and tags that match more than one check output metric point, Sensu evaluates all matching metric points against the thresholds. + +### Check configuration requirements for metric threshold evaluation + +To apply metric threshold evaluation, check definitions must include: +- The [`output_metric_format`][10] attribute with a value that specifies one of Sensu's [supported output metric formats][9]. +- The [`output_metric_thresholds`][33] array, with values specified for `name` and `thresholds`. + +In addition, check status must be 0 (OK), indicating that Sensu successfully collected metrics, for the Sensu agent to evaluate the collected metrics against the specified thresholds. + +### Use token substitution in thresholds values + +You can use check [token substitution][22] in values for [`thresholds`][32] `max` and `min` attributes instead of specifying a single constant value. +Check tokens are placeholders that the Sensu agent will replace with the corresponding entity definition attribute values. + +This example shows the `thresholds` array configured to use token substitution for the `max` and `min` attribute values: + +{{< language-toggle >}} + +{{< code yml >}} +thresholds: +- max: '{{ .annotations.system_cpu_used_warning_threshold | default "70.0" }}' + min: '{{ .annotations.system_cpu_used_warning_threshold | default "50.0" }}' + status: 1 +- max: '{{ .annotations.system_cpu_used_warning_threshold | default "80.0" }}' + min: '{{ .annotations.system_cpu_used_warning_threshold | default "40.0" }}' + status: 2 +{{< /code >}} + +{{< code json >}} +{ + "thresholds": [ + { + "max": "{{ .annotations.system_cpu_used_warning_threshold | default \"70.0\" }}", + "min": "{{ .annotations.system_cpu_used_warning_threshold | default \"50.0\" }}", + "status": 1 + }, + { + "max": "{{ .annotations.system_cpu_used_warning_threshold | default \"80.0\" }}", + "min": "{{ .annotations.system_cpu_used_warning_threshold | default \"40.0\" }}", + "status": 2 + } + ] +} +{{< /code >}} + +{{< /language-toggle >}} + +If an entity has an annotation that matches `system_cpu_used_warning_threshold`, the check will substitute the annotation value when executing the check. +If an entity does not have a matching annotation, the check will use the specified default values instead. + +### Add event annotations based on metric threshold evaluation + +If a check definition includes the `output_metric_thresholds` attribute, the check's metric events with non-zero status will include an annotation that lists the reason for the status. +Sensu adds one annotation per matched threshold rule, one annotation per missing metric (`null_status`), and one annotation that lists the global status for the check. + +Annotations based on specified threshold values are similar to this example: + +{{< language-toggle >}} + +{{< code text "YML" >}} +annotations: + sensu.io/output_metric_thresholds/system_mem_used/min/critical: 'The value of "system_mem_used" exceeded the configured threshold (max: 90, actual: 95)' +{{< /code >}} + +{{< code text "JSON" >}} +{ + "annotations": { + "sensu.io/output_metric_thresholds/system_mem_used/min/critical": "The value of \"system_mem_used\" exceeded the configured threshold (max: 90, actual: 95)" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +Annotations based on `null_status` are similar to this example: + +{{< language-toggle >}} + +{{< code text "YML" >}} +annotations: + sensu.io/output_metric_thresholds/system_host_processes/null: 'WARNING: no metric matching "system_host_processes" (namespace="production") was found; expected min: 5 - max: 50 (status: warning) min:2 - max: 75 (status: critical)' +{{< /code >}} + +{{< code text "JSON" >}} +{ + "annotations": { + "sensu.io/output_metric_thresholds/system_host_processes/null": "WARNING: no metric matching \"system_host_processes\" (namespace=\"production\") was found; expected min: 5 - max: 50 (status: warning) min:2 - max: 75 (status: critical)" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +Annotations based on global status for the check are similar to this example: + +{{< language-toggle >}} + +{{< code text "YML" >}} +annotations: + sensu.io/notifications/critical: 'The value of node_load1 exceeded the configured threshold (max: 4.0, actual: 5.263671875).' +{{< /code >}} + +{{< code text "JSON" >}} +{ + "annotations": { + "sensu.io/notifications/critical": "The value of node_load1 exceeded the configured threshold (max: 4.0, actual: 5.263671875)." + } +} +{{< /code >}} + +{{< /language-toggle >}} + +Annotations based on global `null_status` for the check are similar to this example: + +{{< language-toggle >}} + +{{< code text "YML" >}} +annotations: + sensu.io/notifications/unknown: 'WARNING: no metric matching "node_load1" (namespace="production") was found; expected min: 4.0 (status: warning); expected max: 6 (status: critical)' +{{< /code >}} + +{{< code text "JSON" >}} +{ + "annotations": { + "sensu.io/notifications/unknown": "WARNING: no metric matching \"node_load1\" (namespace=\"production\") was found; expected min: 4.0 (status: warning); expected max: 6 (status: critical)" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Process extracted and tagged metrics + +Specify the handlers you want to process your Sensu metrics in a [pipeline][23], then reference the pipeline in the check [`pipelines`][3] array. +With handlers, you can route metrics to one or more databases for storing and visualizing metrics, like Elasticsearch, InfluxDB, Grafana, and Graphite. + +Many of our most popular metrics integrations for [time-series and long-term event storage][18] include curated, configurable quick-start templates to integrate Sensu with your existing workflows. +Use [Bonsai][8], the Sensu asset hub, to discover, download, and share dynamic runtime assets for processing metrics. + +To handle both metrics and status events without applying conditional filter logic, configure a pipeline with different workflows for metrics and status. +The events reference includes an [example event with check and metric data][20]. +Read the [pipelines reference][27] for more information about configuring a pipeline with multiple workflows. + +You do not need to add a mutator to your check definition to process metrics with an event handler. +The [metrics attribute][5] format automatically reduces metrics data complexity so event handlers can process metrics effectively. + +## Validate metrics + +If the check output is formatted correctly according to its `output_metric_format`, the metrics will be extracted in Sensu metric format and passed to the observability pipeline. +The Sensu agent will log errors if it cannot parse the check output. + +Use the [debug handler example][24] to write metric events to a file for inspection. +To confirm that the check extracted metrics, inspect the event passed to the handler in the debug-event.json file. +The event will include a top-level [metrics section][5] populated with [metrics points arrays][25] if the Sensu agent correctly ingested the metrics. + +## Metrics specification + +The check specification describes [metrics attributes in checks][19]. + +The event specification describes [metrics attributes in events][5]. + + +[1]: ../checks/#output-metric-tags +[2]: ../../observe-process/aggregate-metrics-statsd/ +[3]: ../checks/#pipelines-attribute +[4]: #extract-metrics-from-check-output +[5]: ../../observe-events/events/#metrics-attribute +[6]: #metric-check-example +[7]: ../prometheus-metrics/ +[8]: https://bonsai.sensu.io/ +[9]: #supported-output-metric-formats +[10]: ../checks/#output-metric-format +[11]: #process-extracted-and-tagged-metrics +[12]: https://bonsai.sensu.io/assets/sensu/sensu-go-graphite-handler +[13]: https://assets.nagios.com/downloads/nagioscore/docs/nagioscore/3/en/perfdata.html +[14]: https://graphite.readthedocs.io/en/latest/feeding-carbon.html#the-plaintext-protocol +[15]: https://docs.influxdata.com/enterprise_influxdb/v1.9/write_protocols/line_protocol_reference/ +[16]: http://opentsdb.net/docs/build/html/user_guide/writing/index.html#data-specification +[17]: https://prometheus.io/docs/instrumenting/exposition_formats/#text-based-format +[18]: ../../../plugins/featured-integrations/#time-series-and-long-term-event-storage +[19]: ../checks/#output-metric-format +[20]: ../../observe-events/events/#example-status-and-metrics-event +[21]: ../checks/#output_metric_tags-attributes +[22]: ../tokens/ +[23]: ../../observe-process/pipelines/ +[24]: ../../../operations/maintain-sensu/troubleshoot#use-a-debug-handler +[25]: ../../observe-events/events/#metrics-points +[26]: https://bonsai.sensu.io/assets/sensu/system-check +[27]: ../../observe-process/pipelines/#workflows +[28]: ../../observe-events/events/ +[29]: ../../observe-events/events/#points-attributes +[30]: ../../observe-process/handler-templates/#available-event-attributes +[31]: ../../../plugins/plugins/ +[32]: ../checks/#thresholds-attributes +[33]: ../checks/#output-metric-thresholds +[34]: ../../../sensu-plus/#add-a-sensu-check +[35]: https://bonsai.sensu.io/assets/sensu/system-check +[36]: ../../observe-events/events/#check-status-attribute diff --git a/content/sensu-go/6.12/observability-pipeline/observe-schedule/monitor-server-resources.md b/content/sensu-go/6.12/observability-pipeline/observe-schedule/monitor-server-resources.md new file mode 100644 index 0000000000..e3e5edbd41 --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-schedule/monitor-server-resources.md @@ -0,0 +1,542 @@ +--- +title: "Monitor server resources with checks" +linkTitle: "Monitor Server Resources" +guide_title: "Monitor server resources with checks" +type: "guide" +description: "Sensu lets you monitor server resources with checks. Read this guide to learn about Sensu checks and how to use checks to monitor servers." +weight: 220 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: observe-schedule +--- + +Sensu [checks][3] are commands or scripts the Sensu agent executes that output data and produce an exit code to indicate a state. + +You can use checks to monitor server resources, services, and application health, such as remaining disk space and whether NGINX is running. +This guide includes two check examples to help you monitor server resources: specifically, CPU usage and NGINX status. + +## Requirements + +To follow this guide, install the Sensu [backend][4], make sure at least one Sensu [agent][18] is running, and configure [sensuctl][17] to connect to the backend as the [`admin` user][19]. + +## Configure a Sensu entity + +Every Sensu agent has a defined set of subscriptions that determine which checks the agent will execute. +For an agent to execute a specific check, you must specify the same subscription in the agent configuration and the check definition. +To run the CPU and NGINX webserver checks, you'll need a Sensu entity with the subscriptions `system` and `webserver`. + +{{% notice note %}} +**NOTE**: In production, your CPU and NGINX servers would be different entities, with the `system` subscription specified for the CPU entity and the `webserver` subscription specified for the NGINX entity. +To keep things streamlined, this guide uses one entity to represent both. +{{% /notice %}} + +To add the `system` and `webserver` subscriptions to the entity the Sensu agent is observing, first find your agent entity name: + +{{< code shell >}} +sensuctl entity list +{{< /code >}} + +The `ID` is the name of your entity. + +Replace `` with the name of your agent entity in the following sensuctl command. +Run: + +{{< code shell >}} +sensuctl entity update +{{< /code >}} + +- For `Entity Class`, press enter. +- For `Subscriptions`, type `system,webserver` and press enter. + +Confirm both Sensu services are running: + +{{< code shell >}} +systemctl status sensu-backend && systemctl status sensu-agent +{{< /code >}} + +The response should indicate `active (running)` for both the Sensu backend and agent. + +## Register dynamic runtime assets + +You can write shell scripts in the `command` field of your check definitions, but we recommend using existing check plugins instead. +Check plugins must be available on the host where the agent is running for the agent to execute the check. +This guide uses dynamic runtime assets to manage plugin installation. + +### Register the sensu/check-cpu-usage asset + +The sensu/check-cpu-usage dynamic runtime asset includes the `check-cpu-usage` command, which your CPU check will rely on. + +To register the sensu/check-cpu-usage dynamic runtime asset, run: + +{{< code shell >}} +sensuctl asset add sensu/check-cpu-usage:0.2.2 -r check-cpu-usage +{{< /code >}} + +The response will confirm that the asset was added: + +{{< code text >}} +fetching bonsai asset: sensu/check-cpu-usage:0.2.2 +added asset: sensu/check-cpu-usage:0.2.2 + +You have successfully added the Sensu asset resource, but the asset will not get downloaded until +it's invoked by another Sensu resource (ex. check). To add this runtime asset to the appropriate +resource, populate the "runtime_assets" field with ["check-cpu-usage"]. +{{< /code >}} + +This example uses the `-r` (rename) flag to specify a shorter name for the dynamic runtime asset: `check-cpu-usage`. + +### Register the sensu/sensu-processes-check asset + +Then, use this command to register the sensu/sensu-processes-check dynamic runtime asset, which you'll use later for your webserver check: + +{{< code shell >}} +sensuctl asset add sensu/sensu-processes-check:0.2.0 -r sensu-processes-check +{{< /code >}} + +To confirm that both dynamic runtime assets are ready to use, run: + +{{< code shell >}} +sensuctl asset list +{{< /code >}} + +The response should list the renamed check-cpu-usage and sensu-processes-check dynamic runtime assets: + +{{< code text >}} + Name URL Hash +──────────────────────── ─────────────────────────────────────────────────────────────────────────────── ────────── + check-cpu-usage //assets.bonsai.sensu.io/.../check-cpu-usage_0.2.2_windows_amd64.tar.gz 900cfdf + check-cpu-usage //assets.bonsai.sensu.io/.../check-cpu-usage_0.2.2_darwin_amd64.tar.gz db81ee7 + check-cpu-usage //assets.bonsai.sensu.io/.../check-cpu-usage_0.2.2_linux_armv7.tar.gz 400aacc + check-cpu-usage //assets.bonsai.sensu.io/.../check-cpu-usage_0.2.2_linux_arm64.tar.gz bef7802 + check-cpu-usage //assets.bonsai.sensu.io/.../check-cpu-usage_0.2.2_linux_386.tar.gz a2dcb53 + check-cpu-usage //assets.bonsai.sensu.io/.../check-cpu-usage_0.2.2_linux_amd64.tar.gz 2453973 + sensu-processes-check //assets.bonsai.sensu.io/.../sensu-processes-check_0.2.0_windows_amd64.tar.gz 42e2d71 + sensu-processes-check //assets.bonsai.sensu.io/.../sensu-processes-check_0.2.0_darwin_amd64.tar.gz 957c008 + sensu-processes-check //assets.bonsai.sensu.io/.../sensu-processes-check_0.2.0_linux_armv7.tar.gz 20cc5b1 + sensu-processes-check //assets.bonsai.sensu.io/.../sensu-processes-check_0.2.0_linux_arm64.tar.gz c68b5f0 + sensu-processes-check //assets.bonsai.sensu.io/.../sensu-processes-check_0.2.0_linux_386.tar.gz 4c47caa + sensu-processes-check //assets.bonsai.sensu.io/.../sensu-processes-check_0.2.0_linux_amd64.tar.gz 70e830f +{{< /code >}} + +Because plugins are published for multiple platforms, including Linux and Windows, the output will include multiple entries for each of the dynamic runtime assets. + +{{% notice note %}} +**NOTE**: Sensu does not download and install dynamic runtime asset builds onto the system until they are needed for command execution. +{{% /notice %}} + +## Create a check to monitor a server + +Now that the dynamic runtime assets are registered, create a check named `check_cpu` that runs the command `check-cpu-usage -w 75 -c 90` with the check-cpu-usage dynamic runtime asset at an interval of 60 seconds for all entities subscribed to the `system` subscription. +This check generates a warning event (`-w`) when CPU usage reaches 75% and a critical alert (`-c`) at 90%. + +{{< code shell >}} +sensuctl check create check_cpu \ +--command 'check-cpu-usage -w 75 -c 90' \ +--interval 60 \ +--subscriptions system \ +--runtime-assets check-cpu-usage +{{< /code >}} + +You should receive a confirmation message: + +{{< code text >}} +Created +{{< /code >}} + +To view the complete resource definition for `check_cpu`, run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl check info check_cpu --format yaml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl check info check_cpu --format wrapped-json +{{< /code >}} + +{{< /language-toggle >}} + +The sensuctl response will include the complete `check_cpu` resource definition in the specified format: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: check_cpu +spec: + check_hooks: null + command: check-cpu-usage -w 75 -c 90 + env_vars: null + handlers: [] + high_flap_threshold: 0 + interval: 60 + low_flap_threshold: 0 + output_metric_format: "" + output_metric_handlers: null + pipelines: [] + proxy_entity_name: "" + publish: true + round_robin: false + runtime_assets: + - check-cpu-usage + secrets: null + stdin: false + subdue: null + subscriptions: + - system + timeout: 0 + ttl: 0 +{{< /code >}} + +{{< code json >}} +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "check_cpu" + }, + "spec": { + "check_hooks": null, + "command": "check-cpu-usage -w 75 -c 90", + "env_vars": null, + "handlers": [], + "high_flap_threshold": 0, + "interval": 60, + "low_flap_threshold": 0, + "output_metric_format": "", + "output_metric_handlers": null, + "pipelines": [], + "proxy_entity_name": "", + "publish": true, + "round_robin": false, + "runtime_assets": [ + "check-cpu-usage" + ], + "secrets": null, + "stdin": false, + "subdue": null, + "subscriptions": [ + "system" + ], + "timeout": 0, + "ttl": 0 + } +} +{{< /code >}} + +{{< /language-toggle >}} + +### Validate the CPU check + +The Sensu agent uses WebSocket to communicate with the Sensu backend, sending event data as JSON messages. +As your checks run, the Sensu agent captures check standard output (stdout) or standard error (stderr). +This data will be included in the JSON payload the agent sends to your Sensu backend as the event data. + +It might take a few moments after you create the check for the check to be scheduled on the entity and the event to return to the Sensu backend. +Use sensuctl to view the event data and confirm that Sensu is monitoring CPU usage: + +{{< code shell >}} +sensuctl event list +{{< /code >}} + +The response should list the `check_cpu` check, returning an OK status (`0`) + +{{< code text >}} + Entity Check Output Status Silenced Timestamp UUID +─────────────── ─────────── ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── ──────── ────────── ─────────────────────────────── ─────────────────────────────────────── + sensu-centos check_cpu check-cpu-usage OK: 1.02% CPU usage | cpu_idle=98.98, cpu_system=0.51, cpu_user=0.51, cpu_nice=0.00, cpu_iowait=0.00, cpu_irq=0.00, cpu_softirq=0.00, cpu_steal=0.00, cpu_guest=0.00, cpu_guestnice=0.00 0 false 2021-10-06 19:25:43 +0000 UTC xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx +{{< /code >}} + +## Create a check to monitor a webserver + +In this section, you'll create a check to monitor an NGINX webserver, similar to the CPU check you created in the previous section but using the `webserver` subscription rather than `system`. + +### Install and configure NGINX + +The webserver check requires a running NGINX service, so you'll need to install and configure NGINX. + +{{% notice note %}} +**NOTE**: You may need to install and update the EPEL repository with `sudo yum install epel-release` and `sudo yum update` before you can install NGINX. +{{% /notice %}} + +Install NGINX: + +{{< code shell >}} +sudo yum install nginx +{{< /code >}} + +Enable and start the NGINX service: + +{{< code shell >}} +systemctl enable nginx && systemctl start nginx +{{< /code >}} + +Verify that NGINX is serving webpages: + +{{< code shell >}} +curl -sI http://localhost +{{< /code >}} + +The response should include `HTTP/1.1 200 OK` to indicate that NGINX processed your request as expected: + +{{< code text >}} +HTTP/1.1 200 OK +Server: nginx/1.20.1 +Date: Wed, 06 Oct 2021 19:35:14 GMT +Content-Type: text/html +Content-Length: 4833 +Last-Modified: Fri, 16 May 2014 15:12:48 GMT +Connection: keep-alive +ETag: "xxxxxxxx-xxxx" +Accept-Ranges: bytes +{{< /code >}} + +With your NGINX service running, you can configure the webserver check. + +### Create the webserver check definition + +Create a check that uses `sensu-processes-check` in the command to search for the string `nginx`. +The `nginx_service` check will run at an interval of 15 seconds and determine whether the `nginx` service is among the running processes for all entities subscribed to the `webserver` subscription. + +To create the `nginx_service` check, run the following command: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +cat << EOF | sensuctl create +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: nginx_service +spec: + command: > + sensu-processes-check + --search + '[{"search_string": "nginx"}]' + subscriptions: + - webserver + interval: 15 + publish: true + runtime_assets: + - sensu-processes-check +EOF +{{< /code >}} + +{{< code shell "JSON" >}} +cat << EOF | sensuctl create +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "nginx_service" + }, + "spec": { + "command": "sensu-processes-check --search '[{\"search_string\": \"nginx\"}]'\n", + "subscriptions": [ + "webserver" + ], + "interval": 15, + "publish": true, + "runtime_assets": [ + "sensu-processes-check" + ] + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + +You should receive a confirmation message: + +{{< code text >}} +Created +{{< /code >}} + +To view the complete resource definition for `nginx_service`, run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl check info nginx_service --format yaml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl check info nginx_service --format wrapped-json +{{< /code >}} + +{{< /language-toggle >}} + +The sensuctl response will include the complete `nginx_service` resource definition in the specified format: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: nginx_service +spec: + check_hooks: null + command: | + sensu-processes-check --search '[{"search_string": "nginx"}]' + env_vars: null + handlers: [] + high_flap_threshold: 0 + interval: 15 + low_flap_threshold: 0 + output_metric_format: "" + output_metric_handlers: null + pipelines: [] + proxy_entity_name: "" + publish: true + round_robin: false + runtime_assets: + - sensu-processes-check + secrets: null + stdin: false + subdue: null + subscriptions: + - webserver + timeout: 0 + ttl: 0 +{{< /code >}} + +{{< code json >}} +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "nginx_service" + }, + "spec": { + "check_hooks": null, + "command": "sensu-processes-check --search '[{\"search_string\": \"nginx\"}]'\n", + "env_vars": null, + "handlers": [], + "high_flap_threshold": 0, + "interval": 15, + "low_flap_threshold": 0, + "output_metric_format": "", + "output_metric_handlers": null, + "pipelines": [], + "proxy_entity_name": "", + "publish": true, + "round_robin": false, + "runtime_assets": [ + "sensu-processes-check" + ], + "secrets": null, + "stdin": false, + "subdue": null, + "subscriptions": [ + "webserver" + ], + "timeout": 0, + "ttl": 0 + } +} +{{< /code >}} + +{{< /language-toggle >}} + +### Validate the webserver check + +It might take a few moments after you create the check for the check to be scheduled on the entity and the event to return to the Sensu backend. +Use sensuctl to view event data and confirm that Sensu is monitoring the NGINX webserver status: + +{{< code shell >}} +sensuctl event list +{{< /code >}} + +The response should list the `nginx_service` check, returning an OK status (`0`): + +{{< code text >}} + Entity Check Output Status Silenced Timestamp UUID +─────────────── ─────────────── ──────────────────────────────────────────────────────────────────────── ──────── ────────── ─────────────────────────────── ─────────────────────────────────────── + sensu-centos nginx_service OK | 2 >= 1 (found >= required) evaluated true for "nginx" 0 false 2021-11-08 16:59:34 +0000 UTC xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + Status - OK +{{< /code >}} + +### Simulate a critical event + +To manually generate a critical event for your `nginx_service` check, stop the NGINX service. +Run: + +{{< code shell >}} +systemctl stop nginx +{{< /code >}} + +When you stop the service, the check will generate a critical event. +After a few moments, run: + +{{< code shell >}} +sensuctl event list +{{< /code >}} + +The response should list the `nginx_service` check, returning a CRITICAL status (`2`): + +{{< code text >}} + Entity Check Output Status Silenced Timestamp UUID +─────────────── ─────────────── ──────────────────────────────────────────────────────────────────────── ──────── ────────── ─────────────────────────────── ─────────────────────────────────────── + sensu-centos nginx_service CRITICAL | 0 >= 1 (found >= required) evaluated false for "nginx" 2 false 2021-11-08 17:02:04 +0000 UTC xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + Status - CRITICAL +{{< /code >}} + +Restart the NGINX service to clear the event: + +{{< code shell >}} +systemctl start nginx +{{< /code >}} + +After a moment, you can verify that the event cleared: + +{{< code shell >}} +sensuctl event list +{{< /code >}} + +The response should list the `nginx_service` check with an OK status (`0`). + +## What's next + +Now that you know how to create checks to monitor CPU usage and NGINX webserver status, read the [checks reference][3] and [assets reference][2] for more detailed information. +Or, learn how to [collect and analyze metrics][7] or [monitor external resources with proxy checks and entities][5]. + +You can also create pipelines to send alerts to [email][13], [PagerDuty][9], or [Slack][6] based on the status events your checks are generating. +Or, send status and metrics data to [Sumo Logic][20]. +Read the [pipelines reference][10] for information about configuring observability event processing workflows with event filters, mutators, and handlers. + +To share, reuse, and maintain the checks you created in this guide just like you would code, [save the check definitions to a file][11] and start building a [monitoring as code repository][12]. + +Learn more about the [dynamic runtime assets][2] this guide uses: [sensu/check-cpu-usage][1] and [sensu/sensu-processes-check][15]. + + +[1]: https://bonsai.sensu.io/assets/sensu/check-cpu-usage +[2]: ../../../plugins/assets/ +[3]: ../checks/ +[4]: ../../../operations/deploy-sensu/install-sensu/#install-the-sensu-backend +[5]: ../../observe-entities/monitor-external-resources/ +[6]: ../../observe-process/send-slack-alerts/ +[7]: ../collect-metrics-with-checks/ +[8]: ../subscriptions/ +[9]: ../../observe-process/send-pagerduty-alerts/ +[10]: ../../observe-process/pipelines/ +[11]: ../../../operations/monitoring-as-code/#build-as-you-go +[12]: ../../../operations/monitoring-as-code/ +[13]: ../../observe-process/send-email-alerts/ +[14]: https://bonsai.sensu.io/ +[15]: https://bonsai.sensu.io/assets/sensu/sensu-processes-check +[16]: ../../../sensuctl/ +[17]: ../../../operations/deploy-sensu/install-sensu/#install-sensuctl +[18]: ../../../operations/deploy-sensu/install-sensu/#install-sensu-agents +[19]: ../../../operations/control-access/rbac/#default-users +[20]: ../../observe-process/send-data-sumo-logic/ diff --git a/content/sensu-go/6.12/observability-pipeline/observe-schedule/prometheus-metrics.md b/content/sensu-go/6.12/observability-pipeline/observe-schedule/prometheus-metrics.md new file mode 100644 index 0000000000..c91c4c5c7c --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-schedule/prometheus-metrics.md @@ -0,0 +1,550 @@ +--- +title: "Collect Prometheus metrics with Sensu" +linkTitle: "Collect Prometheus Metrics" +guide_title: "Collect Prometheus metrics with Sensu" +type: "guide" +description: "Use the Sensu Prometheus Collector integration to collect Prometheus metrics so Sensu can route the collected metrics to a time-series database like InfluxDB." +weight: 160 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: observe-schedule +--- + +The Prometheus ecosystem contains a number of actively maintained exporters, such as the [node exporter][5] for reporting hardware and operating system metrics or Google's [cAdvisor exporter][6] for monitoring containers. +These exporters expose metrics that Sensu can collect and route to one or more time-series databases. +Sensu and Prometheus can run in parallel, complementing each other and making use of environments where Prometheus is already deployed. + +You can use the [HTTP checks collection][19] to create checks that collect [metrics][10] from a [Prometheus exporter][2] or the [Prometheus query API][3]. +This allows Sensu to route the collected metrics to one or more time-series databases, such as InfluxDB or Graphite. + +At the end of this guide, Prometheus will be scraping metrics. +The check that uses the sensu/http-checks asset will query the Prometheus API as a Sensu check and send the metrics to an InfluxDB Sensu handler, which will send metrics to an InfluxDB instance. +Finally, Grafana will query InfluxDB to display the collected metrics. + +## Requirements + +To follow this guide, [install][4] the Sensu backend, make sure at least one Sensu [agent][21] is running, and install and configure [sensuctl][22]. + +The examples in this guide use CentOS 7 as the operating system, with all components running on the same compute resource. +Commands and steps may change for different distributions or if components are running on different compute resources. + +## Configure a Sensu entity + +Use sensuctl to add the `app_tier` subscription to one of your entities. +Before you run the following code, replace `` with the name of the entity on your system. + +{{% notice note %}} +**NOTE**: To find your entity name, run `sensuctl entity list`. +The `ID` is the name of your entity. +{{% /notice %}} + +{{< code shell >}} +sensuctl entity update +{{< /code >}} + +- For `Entity Class`, press enter. +- For `Subscriptions`, type `app_tier` and press enter. + +Run this command to confirm both Sensu services are running: + +{{< code shell >}} +systemctl status sensu-backend && systemctl status sensu-agent +{{< /code >}} + +The response should indicate `active (running)` for both the Sensu backend and agent. + +## Install and configure Prometheus + +Download and extract Prometheus with these commands: + +{{< code shell >}} +wget https://github.com/prometheus/prometheus/releases/download/v2.6.0/prometheus-2.6.0.linux-amd64.tar.gz +{{< /code >}} + +{{< code shell >}} +tar xvfz prometheus-*.tar.gz +{{< /code >}} + +{{< code shell >}} +cd prometheus-* +{{< /code >}} + +Replace the default `prometheus.yml` configuration file with the following configuration: + +{{< code shell >}} +global: + scrape_interval: 15s + external_labels: + monitor: 'codelab-monitor' + +scrape_configs: + - job_name: 'prometheus' + scrape_interval: 5s + static_configs: + - targets: ['localhost:9090'] +{{< /code >}} + +Start Prometheus in the background: + +{{< code shell >}} +nohup ./prometheus --config.file=prometheus.yml > prometheus.log 2>&1 & +{{< /code >}} + +Ensure Prometheus is running: + +{{< code shell >}} +ps -ef | grep "[p]rometheus" +{{< /code >}} + +The response should be similar to this example: + +{{< code text >}} +vagrant 7647 3937 2 22:23 pts/0 00:00:00 ./prometheus --config.file=prometheus.yml +{{< /code >}} + +## Install and configure InfluxDB + +Add an InfluxDB repo: + +{{< code shell >}} +echo "[influxdb] +name = InfluxDB Repository - RHEL \$releasever +baseurl = https://repos.influxdata.com/rhel/\$releasever/\$basearch/stable +enabled = 1 +gpgcheck = 1 +gpgkey = https://repos.influxdata.com/influxdb.key" | sudo tee /etc/yum.repos.d/influxdb.repo +{{< /code >}} + +Install InfluxDB: + +{{< code shell >}} +sudo yum -y install influxdb +{{< /code >}} + +Open `/etc/influxdb/influxdb.conf` and uncomment the `http` API line: + +{{< code shell >}} +[http] + # Determines whether HTTP endpoint is enabled. + enabled = true +{{< /code >}} + +Start InfluxDB: + +{{< code shell >}} +sudo systemctl start influxdb +{{< /code >}} + +Add the Sensu user and database with these commands: + +{{< code shell >}} +influx -execute "CREATE DATABASE sensu" +{{< /code >}} + +{{< code shell >}} +influx -execute "CREATE USER sensu WITH PASSWORD 'sensu'" +{{< /code >}} + +{{< code shell >}} +influx -execute "GRANT ALL ON sensu TO sensu" +{{< /code >}} + +## Install and configure Grafana + +Install Grafana: + +{{< code shell >}} +sudo yum install -y https://s3-us-west-2.amazonaws.com/grafana-releases/release/grafana-5.1.4-1.x86_64.rpm +{{< /code >}} + +Change Grafana's listen port so that it does not conflict with the Sensu web UI: + +{{< code shell >}} +sudo sed -i 's/^;http_port = 3000/http_port = 4000/' /etc/grafana/grafana.ini +{{< /code >}} + +Create a `/etc/grafana/provisioning/datasources/influxdb.yaml` file, and add an InfluxDB data source: + +{{< code yml >}} +apiVersion: 1 + +deleteDatasources: + - name: InfluxDB + orgId: 1 + +datasources: + - name: InfluxDB + type: influxdb + access: proxy + orgId: 1 + database: sensu + user: grafana + password: grafana + url: http://localhost:8086 +{{< /code >}} + +Start Grafana: + +{{< code shell >}} +sudo systemctl start grafana-server +{{< /code >}} + +## Create a Sensu InfluxDB handler + +### Add the Sensu InfluxDB handler asset + +To add the sensu/sensu-influxdb-handler dynamic runtime asset to Sensu, run the following command: + +{{< code shell >}} +sensuctl asset add sensu/sensu-influxdb-handler:3.7.0 -r sensu-influxdb-handler +{{< /code >}} + +The response will confirm that the asset was added: + +{{< code text >}} +fetching bonsai asset: sensu/sensu-influxdb-handler:3.7.0 +added asset: sensu/sensu-influxdb-handler:3.7.0 + +You have successfully added the Sensu asset resource, but the asset will not get downloaded until +it's invoked by another Sensu resource (ex. check). To add this runtime asset to the appropriate +resource, populate the "runtime_assets" field with ["sensu-influxdb-handler"]. +{{< /code >}} + +This example uses the `-r` (rename) flag to specify a shorter name for the dynamic runtime asset: `sensu-influxdb-handler`. + +To confirm that the `sensu-influxdb-handler` asset is ready to use, run: + +{{< code shell >}} +sensuctl asset list +{{< /code >}} + +The response should list the `sensu-influxdb-handler` dynamic runtime asset: + +{{< code text >}} + Name URL Hash +───────────────────────────── ──────────────────────────────────────────────────────────────────────────────────── ────────── + sensu-influxdb-handler //assets.bonsai.sensu.io/.../sensu-influxdb-handler_3.7.0_linux_386.tar.gz 6719527 + sensu-influxdb-handler //assets.bonsai.sensu.io/.../sensu-influxdb-handler_3.7.0_linux_amd64.tar.gz d05650d + sensu-influxdb-handler //assets.bonsai.sensu.io/.../sensu-influxdb-handler_3.7.0_linux_armv7.tar.gz 38918c1 + sensu-influxdb-handler //assets.bonsai.sensu.io/.../sensu-influxdb-handler_3.7.0_linux_arm64.tar.gz 944075f + sensu-influxdb-handler //assets.bonsai.sensu.io/.../sensu-influxdb-handler_3.7.0_windows_amd64.tar.gz 8228cbc + sensu-influxdb-handler //assets.bonsai.sensu.io/.../sensu-influxdb-handler_3.7.0_darwin_amd64.tar.gz 7c73e1d +{{< /code >}} + +### Add an InfluxDB handler + +To add the handler definition that uses the Sensu InfluxDB Handler dynamic runtime asset, run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +cat << EOF | sensuctl create +--- +type: Handler +api_version: core/v2 +metadata: + name: influxdb +spec: + command: sensu-influxdb-handler -a 'http://127.0.0.1:8086' -d sensu -u sensu -p sensu + timeout: 10 + type: pipe + runtime_assets: + - sensu-influxdb-handler +EOF +{{< /code >}} + +{{< code shell "JSON" >}} +cat << EOF | sensuctl create +{ + "type": "Handler", + "api_version": "core/v2", + "metadata": { + "name": "influxdb" + }, + "spec": { + "command": "sensu-influxdb-handler -a 'http://127.0.0.1:8086' -d sensu -u sensu -p sensu", + "timeout": 10, + "type": "pipe", + "runtime_assets": [ + "sensu-influxdb-handler" + ] + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + +{{% notice protip %}} +**PRO TIP**: `sensuctl create --file` also accepts files that contain multiple resources' definitions. +You could save both the asset and handler definitions in a single file and use `sensuctl create --file FILE_NAME.EXT` to add them. +{{% /notice %}} + +## Create a pipeline that includes the InfluxDB handler + +Add your handler to a pipeline. +A single pipeline workflow can include one or more filters, one mutator, and one handler. + +In this case, the pipeline includes only the InfluxDB handler you've already configured. +To create the pipeline, run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +cat << EOF | sensuctl create +--- +type: Pipeline +api_version: core/v2 +metadata: + name: prometheus_metrics_workflows +spec: + workflows: + - name: influxdb_metrics + handler: + name: influxdb + type: Handler + api_version: core/v2 +EOF +{{< /code >}} + +{{< code shell "JSON" >}} +cat << EOF | sensuctl create +{ + "type": "Pipeline", + "api_version": "core/v2", + "metadata": { + "name": "prometheus_metrics_workflows" + }, + "spec": { + "workflows": [ + { + "name": "influxdb_metrics", + "handler": { + "name": "influxdb", + "type": "Handler", + "api_version": "core/v2" + } + } + ] + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + +Now you can add the `prometheus_metrics_workflows` pipeline to a check for check output metric extraction. + +## Collect Prometheus metrics with Sensu + +### Add the sensu/http-checks asset + +To add the sensu/http-checks dynamic runtime asset to Sensu, run the following command: + +{{< code shell >}} +sensuctl asset add sensu/http-checks -r http-checks +{{< /code >}} + +The response will confirm that the asset was added: + +{{< code text >}} +no version specified, using latest: 0.8.0 +fetching bonsai asset: sensu/http-checks:0.8.0 +added asset: sensu/http-checks:0.8.0 + +You have successfully added the Sensu asset resource, but the asset will not get downloaded until +it's invoked by another Sensu resource (ex. check). To add this runtime asset to the appropriate +resource, populate the "runtime_assets" field with ["http-checks"]. +{{< /code >}} + +This example uses the `-r` (rename) flag to specify a shorter name for the dynamic runtime asset: `http-checks`. + +To confirm that the `http-checks` asset is ready to use, run: + +{{< code shell >}} +sensuctl asset list +{{< /code >}} + +The response should list the `http-checks` dynamic runtime asset along with the previously added `sensu-influxdb-handler` asset: + +{{< code text >}} + Name URL Hash +───────────────────────────── ──────────────────────────────────────────────────────────────────────────────────── ────────── + http-checks //assets.bonsai.sensu.io/.../http-checks_0.8.0_linux_amd64.tar.gz e1f7f69 + http-checks //assets.bonsai.sensu.io/.../http-checks_0.8.0_linux_386.tar.gz 8629c1e + http-checks //assets.bonsai.sensu.io/.../http-checks_0.8.0_linux_arm64.tar.gz aed9d9b + http-checks //assets.bonsai.sensu.io/.../http-checks_0.8.0_linux_armv7.tar.gz 2948ebc + http-checks //assets.bonsai.sensu.io/.../http-checks_0.8.0_darwin_amd64.tar.gz 29889d1 + http-checks //assets.bonsai.sensu.io/.../http-checks_0.8.0_windows_amd64.tar.gz 167d08f + sensu-influxdb-handler //assets.bonsai.sensu.io/.../sensu-influxdb-handler_3.7.0_linux_386.tar.gz 6719527 + sensu-influxdb-handler //assets.bonsai.sensu.io/.../sensu-influxdb-handler_3.7.0_linux_amd64.tar.gz d05650d + sensu-influxdb-handler //assets.bonsai.sensu.io/.../sensu-influxdb-handler_3.7.0_linux_armv7.tar.gz 38918c1 + sensu-influxdb-handler //assets.bonsai.sensu.io/.../sensu-influxdb-handler_3.7.0_linux_arm64.tar.gz 944075f + sensu-influxdb-handler //assets.bonsai.sensu.io/.../sensu-influxdb-handler_3.7.0_windows_amd64.tar.gz 8228cbc + sensu-influxdb-handler //assets.bonsai.sensu.io/.../sensu-influxdb-handler_3.7.0_darwin_amd64.tar.gz 7c73e1d + +{{< /code >}} + +### Add a Sensu check that references the pipeline + +To add the check definition that uses the sensu/http-checks dynamic runtime asset and your `prometheus_metrics_workflows` pipeline, run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +cat << EOF | sensuctl create +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: prometheus_metrics +spec: + command: http-get --url http://localhost:9090 + handlers: [] + interval: 10 + publish: true + output_metric_format: influxdb_line + pipelines: + - name: prometheus_metrics_workflows + type: Pipeline + api_version: core/v2 + subscriptions: + - app_tier + timeout: 0 + runtime_assets: + - http-checks +EOF +{{< /code >}} + +{{< code shell "JSON" >}} +cat << EOF | sensuctl create +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "prometheus_metrics" + }, + "spec": { + "command": "http-get --url http://localhost:9090", + "handlers": [], + "interval": 10, + "publish": true, + "output_metric_format": "influxdb_line", + "pipelines": [ + { + "name": "prometheus_metrics_workflows", + "type": "Pipeline", + "api_version": "core/v2" + } + ], + "subscriptions": [ + "app_tier" + ], + "timeout": 0, + "runtime_assets": [ + "http-checks" + ] + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + +The check subscription matches the subscription you added to your entity at the beginning of this guide. +The Sensu backend will coordinate check execution for you by comparing the subscriptions in your checks and entities. +Sensu automatically executes a check when the check definition includes a subscription that matches a subscription for a Sensu entity. + +Open the Sensu web UI to view the events generated by the `prometheus_metrics` check. +Visit `http://127.0.0.1:3000`, and log in as the admin user (created during the initialization step when you installed the Sensu backend). + +You can also view the metric event data using sensuctl. +Run: + +{{< code shell >}} +sensuctl event list +{{< /code >}} + +The response should be similar to this example: + +{{< code text >}} + Entity Check Output Status Silenced Timestamp UUID +─────────────── ──────────────────── ──────────────────────────────────────────────────────────────────────── ──────── ────────── ─────────────────────────────── ─────────────────────────────────────── + sensu-centos keepalive Keepalive last sent from sensu-centos at 2022-01-14 15:23:00 +0000 UTC 0 false 2022-01-14 15:23:00 +0000 UTC a9kr7kf8-21h8-459k-v6f8-ad93mf82mkfd + sensu-centos prometheus_metrics up,instance=localhost:9090,job=prometheus value=1 1642173795 0 false 2022-01-14 15:23:15 +0000 UTC sd8j4ls9-34gf-fr77-456g-92384738jd72 +{{< /code >}} + +## Visualize metrics with Grafana + +### Configure a dashboard in Grafana + +Download the Grafana dashboard configuration file from the Sensu docs: + +{{< code shell >}} +curl -O https://docs.sensu.io/sensu-go/latest/files/up_or_down_dashboard.json +{{< /code >}} + +Using the downloaded file, add the dashboard to Grafana with an API call: + +{{< code shell >}} +curl -XPOST -H 'Content-Type: application/json' -d@up_or_down_dashboard.json HTTP://admin:admin@127.0.0.1:4000/api/dashboards/db +{{< /code >}} + +### View metrics in Grafana + +Confirm metrics in Grafana: log in at `http://127.0.0.1:4000`. +Use `admin` for both username and password. + +Click **Home** in the upper left corner, then click the **Up or Down Sample 2** dashboard. +The page should include a graph with initial metrics, similar to this example: + +{{< figure src="/images/go/prometheus_metrics/grafana_up_or_down_detail.png" alt="Example Grafana dashboard for visualizing Prometheus metrics from Sensu" link="/images/go/prometheus_metrics/grafana_up_or_down_detail.png" target="_blank" >}} + +You should now have a working observability pipeline with Prometheus scraping metrics. +The sensu/http-checks dynamic runtime asset runs via the `prometheus_metrics` Sensu check and collects metrics from the Prometheus API. + +The check sends metrics to the `prometheus_metrics_workflows` pipeline, the `influxdb` handler sends the metrics to InfluxDB, and you can visualize the metrics in a Grafana dashboard. + +## What's next + +Learn more about the Sensu resources you created in this guide: + +- [Checks][13] +- [Dynamic runtime assets][11] +- [Handlers][12] and [pipelines][20] +- [Subscriptions][16] + +Now that you know how to extract metrics from check output, you can use a pipeline to [send data to Sumo Logic][23]. + +Visit Bonsai, the Sensu asset index, for more information about the [sensu/sensu-influxdb-handler][18] and [sensu/http-checks][19] assets. +With the sensu/http-checks in your Sensu ecosystem, you can use Prometheus to gather metrics and use Sensu to send them to the proper final destination. +Prometheus has a [comprehensive list][7] of additional exporters to pull in metrics. + +Read about [sensuctl][15] and the Sensu [web UI][14] to learn how to use these features as you develop your monitoring and observability pipelines. + + +[2]: https://prometheus.io/docs/instrumenting/exporters/ +[3]: https://prometheus.io/docs/prometheus/latest/querying/api/ +[4]: ../../../operations/deploy-sensu/install-sensu/#install-the-sensu-backend +[5]: https://github.com/prometheus/node_exporter/ +[6]: https://github.com/google/cadvisor/ +[7]: https://prometheus.io/docs/instrumenting/exporters/ +[8]: ../../../operations/deploy-sensu/install-sensu/#3-initialize +[9]: ../../../operations/monitoring-as-code/ +[10]: ../metrics/ +[11]: ../../../plugins/assets/ +[12]: ../../observe-process/handlers/ +[13]: ../checks/ +[14]: ../../../web-ui/ +[15]: ../../../sensuctl/ +[16]: ../subscriptions/ +[17]: #configure-a-sensu-entity +[18]: https://bonsai.sensu.io/assets/sensu/sensu-influxdb-handler +[19]: https://bonsai.sensu.io/assets/sensu/http-checks +[20]: ../../observe-process/pipelines/ +[21]: ../../../operations/deploy-sensu/install-sensu/#install-sensu-agents +[22]: ../../../operations/deploy-sensu/install-sensu/#install-sensuctl +[23]: ../../observe-process/send-data-sumo-logic/ diff --git a/content/sensu-go/6.12/observability-pipeline/observe-schedule/rule-templates.md b/content/sensu-go/6.12/observability-pipeline/observe-schedule/rule-templates.md new file mode 100644 index 0000000000..d023a049af --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-schedule/rule-templates.md @@ -0,0 +1,963 @@ +--- +title: "Rule templates reference" +linkTitle: "Rule Templates Reference" +reference_title: "Rule templates" +type: "reference" +description: "Rule templates define the conditions under which Sensu will consider a service component online, degraded, or offline for business service monitoring." +weight: 60 +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: observe-schedule +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access business service monitoring (BSM), including rule templates, in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} + +{{% notice note %}} +**NOTE**: Business service monitoring (BSM) is in public preview and is subject to change. +{{% /notice %}} + +Rule templates are the resources that Sensu applies to [service components][3] for business service monitoring (BSM). +A rule template applies to selections of events defined by a service component's query. +This selection of events is the rule's input. + +The rule template evaluates the selection of events using an ECMAScript 5 (JavaScript) expression specified in the rule template's `eval` object and emits a single event based on this evaluation. +For example, a rule template's expression might define the thresholds at which Sensu will consider a service component online, degraded, or offline: + +- Online until fewer than 70% of the service component's events have a check status of OK. +- Degraded while 50-69% of the service component's events have a check status of OK. +- Offline when fewer than 50% of the service component's events have a check status of OK. + +The rule template expression can also create arbitrary events. + +## Built-in rule template: Aggregate + +Sensu includes a built-in rule template, `aggregate`, that allows you to treat the results of multiple disparate check executions executed across multiple disparate systems as a single result (event). +This built-in rule template is ready to use with your service components. + +Reference the rule template name in the `rules.template` field and configure the arguments in the `rules.template.arguments` object in your service component resource definitions. + +Use the `aggregate` rule template for services that can be considered healthy as long as a minimum threshold is satisfied. +For example, you might set the minimum threshold at 10 web servers with an OK status or 70% of processes running with an OK status. + +The `aggregate` rule template is useful in dynamic environments and environments with some tolerance for failure. + +To review the `aggregate` resource definition, retrieve it with a GET request to /enterprise/bsm/v1: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/enterprise/bsm/v1/namespaces/default/rule-templates/aggregate \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The response will include the complete `aggregate` rule template resource definition in JSON format: + +{{< code text >}} +{ + "type": "RuleTemplate", + "api_version": "bsm/v1", + "metadata": { + "name": "aggregate" + }, + "spec": { + "arguments": { + "properties": { + "critical_count": { + "description": "create an event with a critical status if there the number of critical events is equal to or greater than this count", + "type": "number" + }, + "critical_threshold": { + "description": "create an event with a critical status if the percentage of non-zero events is equal to or greater than this threshold", + "type": "number" + }, + "metric_handlers": { + "default": {}, + "description": "metric handlers to use for produced metrics", + "items": { + "type": "string" + }, + "type": "array" + }, + "produce_metrics": { + "default": {}, + "description": "produce metrics from aggregate data and include them in the produced event", + "type": "boolean" + }, + "set_metric_annotations": { + "default": {}, + "description": "annotate the produced event with metric annotations", + "type": "boolean" + }, + "warning_count": { + "description": "create an event with a warning status if there the number of critical events is equal to or greater than this count", + "type": "number" + }, + "warning_threshold": { + "description": "create an event with a warning status if the percentage of non-zero events is equal to or greater than this threshold", + "type": "number" + } + }, + "required": null + }, + "description": "Monitor a distributed service - aggregate one or more events into a single event. This BSM rule template allows you to treat the results of multiple disparate check executions – executed across multiple disparate systems – as a single event. This template is extremely useful in dynamic environments and/or environments that have a reasonable tolerance for failure. Use this template when a service can be considered healthy as long as a minimum threshold is satisfied (for example, at least 5 healthy web servers? at least 70% of N processes healthy?).", + "eval": "\nif (events && events.length == 0) {\n event.check.output = \"WARNING: No events selected for aggregate\n\";\n event.check.status = 1;\n return event;\n}\n\nevent.annotations[\"io.sensu.bsm.selected_event_count\"] = events.length;\n\npercentOK = sensu.PercentageBySeverity(\"ok\");\n\nif (!!args[\"produce_metrics\"]) {\n var handlers = [];\n\n if (!!args[\"metric_handlers\"]) {\n handlers = args[\"metric_handlers\"].slice();\n }\n\n var ts = Math.floor(new Date().getTime() / 1000);\n\n event.timestamp = ts;\n\n var tags = [\n {\n name: \"service\",\n value: event.entity.name\n },\n {\n name: \"entity\",\n value: event.entity.name\n },\n {\n name: \"check\",\n value: event.check.name\n }\n ];\n\n event.metrics = sensu.NewMetrics({\n handlers: handlers,\n points: [\n {\n name: \"percent_non_zero\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"non-zero\"),\n tags: tags\n },\n {\n name: \"percent_ok\",\n timestamp: ts,\n value: percentOK,\n tags: tags\n },\n {\n name: \"percent_warning\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"warning\"),\n tags: tags\n },\n {\n name: \"percent_critical\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"critical\"),\n tags: tags\n },\n {\n name: \"percent_unknown\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"unknown\"),\n tags: tags\n },\n {\n name: \"count_non_zero\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"non-zero\"),\n tags: tags\n },\n {\n name: \"count_ok\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"ok\"),\n tags: tags\n },\n {\n name: \"count_warning\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"warning\"),\n tags: tags\n },\n {\n name: \"count_critical\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"critical\"),\n tags: tags\n },\n {\n name: \"count_unknown\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"unknown\"),\n tags: tags\n }\n ]\n });\n\n if (!!args[\"set_metric_annotations\"]) {\n var i = 0;\n\n while(i < event.metrics.points.length) {\n event.annotations[\"io.sensu.bsm.selected_event_\" + event.metrics.points[i].name] = event.metrics.points[i].value.toString();\n i++;\n }\n }\n}\n\nif (!!args[\"critical_threshold\"] && percentOK <= args[\"critical_threshold\"]) {\n event.check.output = \"CRITICAL: Less than \" + args[\"critical_threshold\"].toString() + \"% of selected events are OK (\" + percentOK.toString() + \"%)\n\";\n event.check.status = 2;\n return event;\n}\n\nif (!!args[\"warning_threshold\"] && percentOK <= args[\"warning_threshold\"]) {\n event.check.output = \"WARNING: Less than \" + args[\"warning_threshold\"].toString() + \"% of selected events are OK (\" + percentOK.toString() + \"%)\n\";\n event.check.status = 1;\n return event;\n}\n\nif (!!args[\"critical_count\"]) {\n crit = sensu.CountBySeverity(\"critical\");\n\n if (crit >= args[\"critical_count\"]) {\n event.check.output = \"CRITICAL: \" + args[\"critical_count\"].toString() + \" or more selected events are in a critical state (\" + crit.toString() + \")\n\";\n event.check.status = 2;\n return event;\n }\n}\n\nif (!!args[\"warning_count\"]) {\n warn = sensu.CountBySeverity(\"warning\");\n\n if (warn >= args[\"warning_count\"]) {\n event.check.output = \"WARNING: \" + args[\"warning_count\"].toString() + \" or more selected events are in a warning state (\" + warn.toString() + \")\n\";\n event.check.status = 1;\n return event;\n }\n}\n\nevent.check.output = \"Everything looks good (\" + percentOK.toString() + \"% OK)\";\nevent.check.status = 0;\n\nreturn event;\n" + } +} +{{< /code >}} + +The configuration for a service component that references the `aggregate` rule template might look like this example: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: ServiceComponent +api_version: bsm/v1 +metadata: + name: webservers +spec: + services: + - website-services + interval: 60 + query: + - type: fieldSelector + value: webserver in event.check.subscriptions + rules: + - template: aggregate + name: webservers_50-70 + arguments: + critical_threshold: 70 + warning_threshold: 50 + handlers: + - slack +{{< /code >}} + +{{< code json >}} +{ + "type": "ServiceComponent", + "api_version": "bsm/v1", + "metadata": { + "name": "webservers" + }, + "spec": { + "services": [ + "website-services" + ], + "interval": 60, + "query": [ + { + "type": "fieldSelector", + "value": "webserver in event.check.subscriptions" + } + ], + "rules": [ + { + "template": "aggregate", + "name": "webservers_50-70", + "arguments": { + "critical_threshold": 70, + "warning_threshold": 50 + } + } + ], + "handlers": [ + "slack" + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Apply rule templates to service components + +Rule templates are general, parameterized resources that can apply to one or more service components. +To apply a rule template to a specific service component: + +- List the rule template name in the service component's `rules.template` field. +- Specify the arguments the rule template requires in the service component's `rules.template.arguments` object. + +Several service components can use the same rule template with different argument values. +For example, a rule template might evaluate one argument, `threshold_ok`, against the number of events with OK status, as represented by the following logic: + +{{< code javascript >}} +if numberEventsOK < threshold_ok { + emit warning event +} +{{< /code >}} + +You can specify a variety of thresholds as arguments in service component definitions that reference this rule template. +One service component might set a `threshold_ok` value at 10; another service component might set the value at 50. +Both service components can make use of the same rule template at the threshold that makes sense for that component. + +Service components can reference more than one rule template. +Sensu evaluates each rule separately, and each rule produces its own event as output. + +## Rule template specification + +### Top-level attributes + +api_version | +-------------|------ +description | Top-level attribute that specifies the Sensu API group and version. For rule template configuration in this version of Sensu, the api_version should always be `bsm/v1`. +required | Required for rule template configuration in `wrapped-json` or `yaml` format. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +api_version: bsm/v1 +{{< /code >}} +{{< code json >}} +{ + "api_version": "bsm/v1" +} +{{< /code >}} +{{< /language-toggle >}} + +metadata | | +-------------|------ +description | Top-level collection of information about the rule template, including `name`, `namespace`, and `created_by` as well as custom `labels` and `annotations`. +required | true +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +metadata: + name: aggregate + namespace: default + created_by: admin + labels: + region: us-west-1 + annotations: + managed_by: ops +{{< /code >}} +{{< code json >}} +{ + "metadata": { + "name": "aggregate", + "namespace": "default", + "created_by": "admin", + "labels": { + "region": "us-west-1" + }, + "annotations": { + "managed_by": "ops" + } + } +} +{{< /code >}} +{{< /language-toggle >}} + +spec | +-------------|------ +description | Top-level map that includes the rule template configuration [spec attributes][5]. +required | Required for rule template configuration in `wrapped-json` or `yaml` format. +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +spec: + arguments: + properties: + critical_count: + description: create an event with a critical status if there the number of + critical events is equal to or greater than this count + type: number + critical_threshold: + description: create an event with a critical status if the percentage of non-zero + events is equal to or greater than this threshold + type: number + metric_handlers: + default: {} + description: metric handlers to use for produced metrics + items: + type: string + type: array + produce_metrics: + default: {} + description: produce metrics from aggregate data and include them in the produced + event + type: boolean + set_metric_annotations: + default: {} + description: annotate the produced event with metric annotations + type: boolean + warning_count: + description: create an event with a warning status if there the number of + critical events is equal to or greater than this count + type: number + warning_threshold: + description: create an event with a warning status if the percentage of non-zero + events is equal to or greater than this threshold + type: number + required: null + description: Monitor a distributed service - aggregate one or more events into a + single event. This BSM rule template allows you to treat the results of multiple + disparate check executions – executed across multiple disparate systems – as a + single event. This template is extremely useful in dynamic environments and/or + environments that have a reasonable tolerance for failure. Use this template when + a service can be considered healthy as long as a minimum threshold is satisfied + (e.g. at least 5 healthy web servers? at least 70% of N processes healthy?). + eval: |2 + if (events && events.length == 0) { + event.check.output = "WARNING: No events selected for aggregate + "; + event.check.status = 1; + return event; + } + event.annotations["io.sensu.bsm.selected_event_count"] = events.length; + percentOK = sensu.PercentageBySeverity("ok"); + if (!!args["produce_metrics"]) { + var ts = Math.floor(new Date().getTime() / 1000); + event.timestamp = ts; + var tags = [ + { + name: "service", + value: event.entity.name + }, + { + name: "entity", + value: event.entity.name + }, + { + name: "check", + value: event.check.name + } + ]; + event.metrics = sensu.NewMetrics({ + points: [ + { + name: "percent_non_zero", + timestamp: ts, + value: sensu.PercentageBySeverity("non-zero"), + tags: tags + }, + { + name: "percent_ok", + timestamp: ts, + value: percentOK, + tags: tags + }, + { + name: "percent_warning", + timestamp: ts, + value: sensu.PercentageBySeverity("warning"), + tags: tags + }, + { + name: "percent_critical", + timestamp: ts, + value: sensu.PercentageBySeverity("critical"), + tags: tags + }, + { + name: "percent_unknown", + timestamp: ts, + value: sensu.PercentageBySeverity("unknown"), + tags: tags + }, + { + name: "count_non_zero", + timestamp: ts, + value: sensu.CountBySeverity("non-zero"), + tags: tags + }, + { + name: "count_ok", + timestamp: ts, + value: sensu.CountBySeverity("ok"), + tags: tags + }, + { + name: "count_warning", + timestamp: ts, + value: sensu.CountBySeverity("warning"), + tags: tags + }, + { + name: "count_critical", + timestamp: ts, + value: sensu.CountBySeverity("critical"), + tags: tags + }, + { + name: "count_unknown", + timestamp: ts, + value: sensu.CountBySeverity("unknown"), + tags: tags + } + ] + }); + if (!!args["metric_handlers"]) { + event.metrics.handlers = args["metric_handlers"].slice(); + } + if (!!args["set_metric_annotations"]) { + var i = 0; + while(i \u003c event.metrics.points.length) { + event.annotations["io.sensu.bsm.selected_event_" + event.metrics.points[i].name] = event.metrics.points[i].value.toString(); + i++; + } + } + } + if (!!args["critical_threshold"] && percentOK \u003c= args["critical_threshold"]) { + event.check.output = "CRITICAL: Less than " + args["critical_threshold"].toString() + "% of selected events are OK (" + percentOK.toString() + "%) + "; + event.check.status = 2; + return event; + } + if (!!args["warning_threshold"] && percentOK \u003c= args["warning_threshold"]) { + event.check.output = "WARNING: Less than " + args["warning_threshold"].toString() + "% of selected events are OK (" + percentOK.toString() + "%) + "; + event.check.status = 1; + return event; + } + if (!!args["critical_count"]) { + crit = sensu.CountBySeverity("critical"); + if (crit \u003e= args["critical_count"]) { + event.check.output = "CRITICAL: " + args["critical_count"].toString() + " or more selected events are in a critical state (" + crit.toString() + ") + "; + event.check.status = 2; + return event; + } + } + if (!!args["warning_count"]) { + warn = sensu.CountBySeverity("warning"); + if (warn \u003e= args["warning_count"]) { + event.check.output = "WARNING: " + args["warning_count"].toString() + " or more selected events are in a warning state (" + warn.toString() + ") + "; + event.check.status = 1; + return event; + } + } + event.check.output = "Everything looks good (" + percentOK.toString() + "% OK)"; + event.check.status = 0; + return event; +{{< /code >}} +{{< code json >}} +{ + "spec": { + "arguments": { + "properties": { + "critical_count": { + "description": "create an event with a critical status if there the number of critical events is equal to or greater than this count", + "type": "number" + }, + "critical_threshold": { + "description": "create an event with a critical status if the percentage of non-zero events is equal to or greater than this threshold", + "type": "number" + }, + "metric_handlers": { + "default": {}, + "description": "metric handlers to use for produced metrics", + "items": { + "type": "string" + }, + "type": "array" + }, + "produce_metrics": { + "default": {}, + "description": "produce metrics from aggregate data and include them in the produced event", + "type": "boolean" + }, + "set_metric_annotations": { + "default": {}, + "description": "annotate the produced event with metric annotations", + "type": "boolean" + }, + "warning_count": { + "description": "create an event with a warning status if there the number of critical events is equal to or greater than this count", + "type": "number" + }, + "warning_threshold": { + "description": "create an event with a warning status if the percentage of non-zero events is equal to or greater than this threshold", + "type": "number" + } + }, + "required": null + }, + "description": "Monitor a distributed service - aggregate one or more events into a single event. This BSM rule template allows you to treat the results of multiple disparate check executions – executed across multiple disparate systems – as a single event. This template is extremely useful in dynamic environments and/or environments that have a reasonable tolerance for failure. Use this template when a service can be considered healthy as long as a minimum threshold is satisfied (e.g. at least 5 healthy web servers? at least 70% of N processes healthy?).", + "eval": "\nif (events \\u0026\\u0026 events.length == 0) {\n event.check.output = \"WARNING: No events selected for aggregate\n\";\n event.check.status = 1;\n return event;\n}\n\nevent.annotations[\"io.sensu.bsm.selected_event_count\"] = events.length;\n\npercentOK = sensu.PercentageBySeverity(\"ok\");\n\nif (!!args[\"produce_metrics\"]) {\n var ts = Math.floor(new Date().getTime() / 1000);\n\n event.timestamp = ts;\n\n var tags = [\n {\n name: \"service\",\n value: event.entity.name\n },\n {\n name: \"entity\",\n value: event.entity.name\n },\n {\n name: \"check\",\n value: event.check.name\n }\n ];\n\n event.metrics = sensu.NewMetrics({\n points: [\n {\n name: \"percent_non_zero\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"non-zero\"),\n tags: tags\n },\n {\n name: \"percent_ok\",\n timestamp: ts,\n value: percentOK,\n tags: tags\n },\n {\n name: \"percent_warning\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"warning\"),\n tags: tags\n },\n {\n name: \"percent_critical\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"critical\"),\n tags: tags\n },\n {\n name: \"percent_unknown\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"unknown\"),\n tags: tags\n },\n {\n name: \"count_non_zero\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"non-zero\"),\n tags: tags\n },\n {\n name: \"count_ok\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"ok\"),\n tags: tags\n },\n {\n name: \"count_warning\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"warning\"),\n tags: tags\n },\n {\n name: \"count_critical\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"critical\"),\n tags: tags\n },\n {\n name: \"count_unknown\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"unknown\"),\n tags: tags\n }\n ]\n });\n\n if (!!args[\"metric_handlers\"]) {\n event.metrics.handlers = args[\"metric_handlers\"].slice();\n }\n\n if (!!args[\"set_metric_annotations\"]) {\n var i = 0;\n\n while(i \\u003c event.metrics.points.length) {\n event.annotations[\"io.sensu.bsm.selected_event_\" + event.metrics.points[i].name] = event.metrics.points[i].value.toString();\n i++;\n }\n }\n}\n\nif (!!args[\"critical_threshold\"] \\u0026\\u0026 percentOK \\u003c= args[\"critical_threshold\"]) {\n event.check.output = \"CRITICAL: Less than \" + args[\"critical_threshold\"].toString() + \"% of selected events are OK (\" + percentOK.toString() + \"%)\n\";\n event.check.status = 2;\n return event;\n}\n\nif (!!args[\"warning_threshold\"] \\u0026\\u0026 percentOK \\u003c= args[\"warning_threshold\"]) {\n event.check.output = \"WARNING: Less than \" + args[\"warning_threshold\"].toString() + \"% of selected events are OK (\" + percentOK.toString() + \"%)\n\";\n event.check.status = 1;\n return event;\n}\n\nif (!!args[\"critical_count\"]) {\n crit = sensu.CountBySeverity(\"critical\");\n\n if (crit \\u003e= args[\"critical_count\"]) {\n event.check.output = \"CRITICAL: \" + args[\"critical_count\"].toString() + \" or more selected events are in a critical state (\" + crit.toString() + \")\n\";\n event.check.status = 2;\n return event;\n }\n}\n\nif (!!args[\"warning_count\"]) {\n warn = sensu.CountBySeverity(\"warning\");\n\n if (warn \\u003e= args[\"warning_count\"]) {\n event.check.output = \"WARNING: \" + args[\"warning_count\"].toString() + \" or more selected events are in a warning state (\" + warn.toString() + \")\n\";\n event.check.status = 1;\n return event;\n }\n}\n\nevent.check.output = \"Everything looks good (\" + percentOK.toString() + \"% OK)\";\nevent.check.status = 0;\n\nreturn event;\n" + } +} +{{< /code >}} +{{< /language-toggle >}} + +type | +-------------|------ +description | Top-level attribute that specifies the resource type. For rule template configuration, the type should always be `RuleTemplate`. +required | Required for rule template configuration in `wrapped-json` or `yaml` format. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +type: RuleTemplate +{{< /code >}} +{{< code json >}} +{ + "type": "RuleTemplate" +} +{{< /code >}} +{{< /language-toggle >}} + +### Metadata attributes + +| annotations | | +-------------|------ +description | Non-identifying metadata to include with observation event data that you can access with [event filters][8]. You can use annotations to add data that's meaningful to people or external tools that interact with Sensu.

    In contrast to labels, you cannot use annotations in [API response filtering][11], [sensuctl response filtering][12], or [web UI views][10]. +required | false +type | Map of key-value pairs. Keys and values can be any valid UTF-8 string. +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +annotations: + managed-by: ops +{{< /code >}} +{{< code json >}} +{ + "annotations": { + "managed-by": "ops" + } +} +{{< /code >}} +{{< /language-toggle >}} + +| created_by | | +-------------|------ +description | Username of the Sensu user who created the rule template or last updated the rule template. Sensu automatically populates the `created_by` field when the rule template is created or updated. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +created_by: admin +{{< /code >}} +{{< code json >}} +{ + "created_by": "admin" +} +{{< /code >}} +{{< /language-toggle >}} + +| labels | | +-------------|------ +description | Custom attributes to include with observation event data that you can use for response and web UI view filtering.

    If you include labels in your event data, you can filter [API responses][11], [sensuctl responses][12], and [web UI views][9] based on them. In other words, labels allow you to create meaningful groupings for your data.

    Limit labels to metadata you need to use for response filtering. For complex, non-identifying metadata that you will *not* need to use in response filtering, use annotations rather than labels. +required | false +type | Map of key-value pairs. Keys can contain only letters, numbers, and underscores and must start with a letter. Values can be any valid UTF-8 string. +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +labels: + region: us-west-1 +{{< /code >}} +{{< code json >}} +{ + "labels": { + "region": "us-west-1" + } +} +{{< /code >}} +{{< /language-toggle >}} + +name | | +-------------|------ +description | Name for the rule template that is used internally by Sensu. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +name: aggregate +{{< /code >}} +{{< code json >}} +{ + "name": "aggregate" +} +{{< /code >}} +{{< /language-toggle >}} + +namespace | | +-------------|------ +description | [Sensu RBAC namespace][6] that the rule template belongs to. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +namespace: default +{{< /code >}} +{{< code json >}} +{ + "namespace": "default" +} +{{< /code >}} +{{< /language-toggle >}} + +### Spec attributes + +arguments | +-------------|------ +description | The rule template's [arguments][7] using [JSON Schema][1] properties. +required | true +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +arguments: + properties: + critical_count: + description: create an event with a critical status if there the number of critical + events is equal to or greater than this count + type: number + critical_threshold: + description: create an event with a critical status if the percentage of non-zero + events is equal to or greater than this threshold + type: number + metric_handlers: + default: {} + description: metric handlers to use for produced metrics + items: + type: string + type: array + produce_metrics: + default: {} + description: produce metrics from aggregate data and include them in the produced + event + type: boolean + set_metric_annotations: + default: {} + description: annotate the produced event with metric annotations + type: boolean + warning_count: + description: create an event with a warning status if there the number of critical + events is equal to or greater than this count + type: number + warning_threshold: + description: create an event with a warning status if the percentage of non-zero + events is equal to or greater than this threshold + type: number + required: null +{{< /code >}} +{{< code json >}} +{ + "arguments": { + "properties": { + "critical_count": { + "description": "create an event with a critical status if there the number of critical events is equal to or greater than this count", + "type": "number" + }, + "critical_threshold": { + "description": "create an event with a critical status if the percentage of non-zero events is equal to or greater than this threshold", + "type": "number" + }, + "metric_handlers": { + "default": { + }, + "description": "metric handlers to use for produced metrics", + "items": { + "type": "string" + }, + "type": "array" + }, + "produce_metrics": { + "default": { + }, + "description": "produce metrics from aggregate data and include them in the produced event", + "type": "boolean" + }, + "set_metric_annotations": { + "default": { + }, + "description": "annotate the produced event with metric annotations", + "type": "boolean" + }, + "warning_count": { + "description": "create an event with a warning status if there the number of critical events is equal to or greater than this count", + "type": "number" + }, + "warning_threshold": { + "description": "create an event with a warning status if the percentage of non-zero events is equal to or greater than this threshold", + "type": "number" + } + }, + "required": null + } +} +{{< /code >}} +{{< /language-toggle >}} + +description | +-------------|------ +description | Plain text description of the rule template's behavior. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +description: Monitor a distributed service - aggregate one or more events into a single event. This BSM rule template allows you to treat the results of multiple disparate check executions – executed across multiple disparate systems – as a single event. This template is extremely useful in dynamic environments and/or environments that have a reasonable tolerance for failure. Use this template when a service can be considered healthy as long as a minimum threshold is satisfied (e.g. at least 5 healthy web servers? at least 70% of N processes healthy?). +{{< /code >}} +{{< code json >}} +{ + "description": "Monitor a distributed service - aggregate one or more events into a single event. This BSM rule template allows you to treat the results of multiple disparate check executions – executed across multiple disparate systems – as a single event. This template is extremely useful in dynamic environments and/or environments that have a reasonable tolerance for failure. Use this template when a service can be considered healthy as long as a minimum threshold is satisfied (e.g. at least 5 healthy web servers? at least 70% of N processes healthy?)." +} +{{< /code >}} +{{< /language-toggle >}} + +eval | +-------------|------ +description | ECMAScript 5 (JavaScript) expression for the rule template to evaluate. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +eval: |2 + if (events && events.length == 0) { + event.check.output = "WARNING: No events selected for aggregate + "; + event.check.status = 1; + return event; + } + event.annotations["io.sensu.bsm.selected_event_count"] = events.length; + percentOK = sensu.PercentageBySeverity("ok"); + if (!!args["produce_metrics"]) { + var ts = Math.floor(new Date().getTime() / 1000); + event.timestamp = ts; + var tags = [ + { + name: "service", + value: event.entity.name + }, + { + name: "entity", + value: event.entity.name + }, + { + name: "check", + value: event.check.name + } + ]; + event.metrics = sensu.NewMetrics({ + points: [ + { + name: "percent_non_zero", + timestamp: ts, + value: sensu.PercentageBySeverity("non-zero"), + tags: tags + }, + { + name: "percent_ok", + timestamp: ts, + value: percentOK, + tags: tags + }, + { + name: "percent_warning", + timestamp: ts, + value: sensu.PercentageBySeverity("warning"), + tags: tags + }, + { + name: "percent_critical", + timestamp: ts, + value: sensu.PercentageBySeverity("critical"), + tags: tags + }, + { + name: "percent_unknown", + timestamp: ts, + value: sensu.PercentageBySeverity("unknown"), + tags: tags + }, + { + name: "count_non_zero", + timestamp: ts, + value: sensu.CountBySeverity("non-zero"), + tags: tags + }, + { + name: "count_ok", + timestamp: ts, + value: sensu.CountBySeverity("ok"), + tags: tags + }, + { + name: "count_warning", + timestamp: ts, + value: sensu.CountBySeverity("warning"), + tags: tags + }, + { + name: "count_critical", + timestamp: ts, + value: sensu.CountBySeverity("critical"), + tags: tags + }, + { + name: "count_unknown", + timestamp: ts, + value: sensu.CountBySeverity("unknown"), + tags: tags + } + ] + }); + if (!!args["metric_handlers"]) { + event.metrics.handlers = args["metric_handlers"].slice(); + } + if (!!args["set_metric_annotations"]) { + var i = 0; + while(i \u003c event.metrics.points.length) { + event.annotations["io.sensu.bsm.selected_event_" + event.metrics.points[i].name] = event.metrics.points[i].value.toString(); + i++; + } + } + } + if (!!args["critical_threshold"] && percentOK \u003c= args["critical_threshold"]) { + event.check.output = "CRITICAL: Less than " + args["critical_threshold"].toString() + "% of selected events are OK (" + percentOK.toString() + "%) + "; + event.check.status = 2; + return event; + } + if (!!args["warning_threshold"] && percentOK \u003c= args["warning_threshold"]) { + event.check.output = "WARNING: Less than " + args["warning_threshold"].toString() + "% of selected events are OK (" + percentOK.toString() + "%) + "; + event.check.status = 1; + return event; + } + if (!!args["critical_count"]) { + crit = sensu.CountBySeverity("critical"); + if (crit \u003e= args["critical_count"]) { + event.check.output = "CRITICAL: " + args["critical_count"].toString() + " or more selected events are in a critical state (" + crit.toString() + ") + "; + event.check.status = 2; + return event; + } + } + if (!!args["warning_count"]) { + warn = sensu.CountBySeverity("warning"); + if (warn \u003e= args["warning_count"]) { + event.check.output = "WARNING: " + args["warning_count"].toString() + " or more selected events are in a warning state (" + warn.toString() + ") + "; + event.check.status = 1; + return event; + } + } + event.check.output = "Everything looks good (" + percentOK.toString() + "% OK)"; + event.check.status = 0; + return event; +{{< /code >}} +{{< code json >}} +{ + "eval": " if (events \\u0026\\u0026 events.length == 0) {\n event.check.output = \"WARNING: No events selected for aggregate\n \";\n event.check.status = 1;\n return event;\n }\n event.annotations[\"io.sensu.bsm.selected_event_count\"] = events.length;\n percentOK = sensu.PercentageBySeverity(\"ok\");\n if (!!args[\"produce_metrics\"]) {\n var ts = Math.floor(new Date().getTime() / 1000);\n event.timestamp = ts;\n var tags = [\n {\n name: \"service\",\n value: event.entity.name\n },\n {\n name: \"entity\",\n value: event.entity.name\n },\n {\n name: \"check\",\n value: event.check.name\n }\n ];\n event.metrics = sensu.NewMetrics({\n points: [\n {\n name: \"percent_non_zero\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"non-zero\"),\n tags: tags\n },\n {\n name: \"percent_ok\",\n timestamp: ts,\n value: percentOK,\n tags: tags\n },\n {\n name: \"percent_warning\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"warning\"),\n tags: tags\n },\n {\n name: \"percent_critical\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"critical\"),\n tags: tags\n },\n {\n name: \"percent_unknown\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"unknown\"),\n tags: tags\n },\n {\n name: \"count_non_zero\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"non-zero\"),\n tags: tags\n },\n {\n name: \"count_ok\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"ok\"),\n tags: tags\n },\n {\n name: \"count_warning\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"warning\"),\n tags: tags\n },\n {\n name: \"count_critical\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"critical\"),\n tags: tags\n },\n {\n name: \"count_unknown\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"unknown\"),\n tags: tags\n }\n ]\n });\n if (!!args[\"metric_handlers\"]) {\n event.metrics.handlers = args[\"metric_handlers\"].slice();\n }\n if (!!args[\"set_metric_annotations\"]) {\n var i = 0;\n while(i \\u003c event.metrics.points.length) {\n event.annotations[\"io.sensu.bsm.selected_event_\" + event.metrics.points[i].name] = event.metrics.points[i].value.toString();\n i++;\n }\n }\n }\n if (!!args[\"critical_threshold\"] \\u0026\\u0026 percentOK \\u003c= args[\"critical_threshold\"]) {\n event.check.output = \"CRITICAL: Less than \" + args[\"critical_threshold\"].toString() + \"% of selected events are OK (\" + percentOK.toString() + \"%)\n \";\n event.check.status = 2;\n return event;\n }\n if (!!args[\"warning_threshold\"] \\u0026\\u0026 percentOK \\u003c= args[\"warning_threshold\"]) {\n event.check.output = \"WARNING: Less than \" + args[\"warning_threshold\"].toString() + \"% of selected events are OK (\" + percentOK.toString() + \"%)\n \";\n event.check.status = 1;\n return event;\n }\n if (!!args[\"critical_count\"]) {\n crit = sensu.CountBySeverity(\"critical\");\n if (crit \\u003e= args[\"critical_count\"]) {\n event.check.output = \"CRITICAL: \" + args[\"critical_count\"].toString() + \" or more selected events are in a critical state (\" + crit.toString() + \")\n \";\n event.check.status = 2;\n return event;\n }\n }\n if (!!args[\"warning_count\"]) {\n warn = sensu.CountBySeverity(\"warning\");\n if (warn \\u003e= args[\"warning_count\"]) {\n event.check.output = \"WARNING: \" + args[\"warning_count\"].toString() + \" or more selected events are in a warning state (\" + warn.toString() + \")\n \";\n event.check.status = 1;\n return event;\n }\n }\n event.check.output = \"Everything looks good (\" + percentOK.toString() + \"% OK)\";\n event.check.status = 0;\n return event;" +} +{{< /code >}} +{{< /language-toggle >}} + +#### Arguments attributes + + + +properties | +-------------|------ +description | List of properties that define the argument's behavior. In [JSON Schema][1]. +required | true +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +properties: + critical_count: + description: create an event with a critical status if there the number of + critical events is equal to or greater than this count + type: number + critical_threshold: + description: create an event with a critical status if the percentage of non-zero + events is equal to or greater than this threshold + type: number + metric_handlers: + default: {} + description: metric handlers to use for produced metrics + items: + type: string + type: array + produce_metrics: + default: {} + description: produce metrics from aggregate data and include them in the produced + event + type: boolean + set_metric_annotations: + default: {} + description: annotate the produced event with metric annotations + type: boolean + warning_count: + description: create an event with a warning status if there the number of + critical events is equal to or greater than this count + type: number + warning_threshold: + description: create an event with a warning status if the percentage of non-zero + events is equal to or greater than this threshold + type: number +{{< /code >}} +{{< code json >}} +{ + "properties": { + "critical_count": { + "description": "create an event with a critical status if there the number of critical events is equal to or greater than this count", + "type": "number" + }, + "critical_threshold": { + "description": "create an event with a critical status if the percentage of non-zero events is equal to or greater than this threshold", + "type": "number" + }, + "metric_handlers": { + "default": {}, + "description": "metric handlers to use for produced metrics", + "items": { + "type": "string" + }, + "type": "array" + }, + "produce_metrics": { + "default": {}, + "description": "produce metrics from aggregate data and include them in the produced event", + "type": "boolean" + }, + "set_metric_annotations": { + "default": {}, + "description": "annotate the produced event with metric annotations", + "type": "boolean" + }, + "warning_count": { + "description": "create an event with a warning status if there the number of critical events is equal to or greater than this count", + "type": "number" + }, + "warning_threshold": { + "description": "create an event with a warning status if the percentage of non-zero events is equal to or greater than this threshold", + "type": "number" + } + }, + "required": null +} +{{< /code >}} +{{< /language-toggle >}} + +required | +-------------|------ +description | List of attributes the rule template argument requires. The listed attributes must be configured in the [properties][2] object. +required | false +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +required: null +{{< /code >}} +{{< code json >}} +{ + "required": null +} +{{< /code >}} +{{< /language-toggle >}} + + +[1]: https://json-schema.org/ +[2]: #rule-properties +[3]: ../service-components/ +[5]: #spec-attributes +[6]: ../../../operations/control-access/namespaces +[7]: #arguments-attributes +[8]: ../../observe-filter/filters/ +[9]: ../../../web-ui/search#search-for-labels +[10]: ../../../web-ui/search/ +[11]: ../../../api/#response-filtering +[12]: ../../../sensuctl/filter-responses/ diff --git a/content/sensu-go/6.12/observability-pipeline/observe-schedule/service-components.md b/content/sensu-go/6.12/observability-pipeline/observe-schedule/service-components.md new file mode 100644 index 0000000000..3160e13da0 --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-schedule/service-components.md @@ -0,0 +1,552 @@ +--- +title: "Service components reference" +linkTitle: "Service Components Reference" +reference_title: "Service components" +type: "reference" +description: "Service components are meaningful selections of Sensu events, like database monitoring events, that allow you to define and manage business service elements." +weight: 80 +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: observe-schedule +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access business service monitoring (BSM), including service components, in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} + +{{% notice note %}} +**NOTE**: Business service monitoring (BSM) is in public preview and is subject to change. +{{% /notice %}} + +Service components are resources for defining and managing elements of a business service in business service monitoring. +A [service entity][10] consists of a number of underlying service components. +A service component is a meaningful selection of Sensu events for a business service, such as database monitoring events. + +A service component includes event selectors to define the events that the component includes, a service component scheduler (either an interval or cron expression), and references to at least one monitoring rule template with arguments. +The monitoring rules are evaluated against aggregate data derived from the service component's selection of events. +Monitoring rules are configured in a separate resource: [rule templates][8]. + +If you delete a resource (for example, an entity, check, or event) that is part of one or more service components, Sensu will automatically remove the deleted resource from the service components. + +## Service component example + +The example service component below is a dependency of the business service entity `website-services`. +Sensu will execute the component at 60-second intervals for `website-services` service entities whose events include the `webserver` subscription. +The monitoring rule template for the service component is `aggregate`. + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: ServiceComponent +api_version: bsm/v1 +metadata: + name: webservers +spec: + handlers: + - slack + interval: 60 + query: + - type: fieldSelector + value: webserver in event.check.subscriptions + rules: + - arguments: + critical_threshold: 70 + warning_threshold: 50 + name: webservers_50-70 + template: aggregate + services: + - website-services +{{< /code >}} + +{{< code json >}} +{ + "type": "ServiceComponent", + "api_version": "bsm/v1", + "metadata": { + "name": "webservers" + }, + "spec": { + "handlers": [ + "slack" + ], + "interval": 60, + "query": [ + { + "type": "fieldSelector", + "value": "webserver in event.check.subscriptions" + } + ], + "rules": [ + { + "arguments": { + "critical_threshold": 70, + "warning_threshold": 50 + }, + "name": "webservers_50-70", + "template": "aggregate" + } + ], + "services": [ + "website-services" + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Service component scheduling + +Sensu executes service components on sensu-backend processes in a round-robin fashion and according to a schedule specified by an interval or a cron expression in the component definition. +During each execution of the service component, Sensu retrieves the events identified in the component's query expression and processes these events according to the monitoring rules specified in the service component definition. +The rules can emit new events based on the component input. + +## Service component specification + +### Top-level attributes + +api_version | +-------------|------ +description | Top-level attribute that specifies the Sensu API group and version. For service component configuration in this version of Sensu, the api_version should always be `bsm/v1`. +required | Required for service component configuration in `wrapped-json` or `yaml` format. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +api_version: bsm/v1 +{{< /code >}} +{{< code json >}} +{ + "api_version": "bsm/v1" +} +{{< /code >}} +{{< /language-toggle >}} + +metadata | | +-------------|------ +description | Top-level collection of information about the service component, including `name`, `namespace`, and `created_by` as well as custom `labels` and `annotations`. +required | true +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +metadata: + name: webservers + namespace: default + created_by: admin + labels: + region: us-west-1 + annotations: + managed_by: ops +{{< /code >}} +{{< code json >}} +{ + "metadata": { + "name": "webservers", + "namespace": "default", + "created_by": "admin", + "labels": { + "region": "us-west-1" + }, + "annotations": { + "managed_by": "ops" + } + } +} +{{< /code >}} +{{< /language-toggle >}} + +spec | +-------------|------ +description | Top-level map that includes the service component configuration [spec attributes][6]. +required | Required for service component configuration in `wrapped-json` or `yaml` format. +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +spec: + handlers: + - slack + interval: 60 + query: + - type: fieldSelector + value: webserver in event.check.subscriptions + rules: + - arguments: + critical_threshold: 70 + warning_threshold: 50 + name: webservers_50-70 + template: aggregate + services: + - website-services +{{< /code >}} +{{< code json >}} +{ + "spec": { + "handlers": [ + "slack" + ], + "interval": 60, + "query": [ + { + "type": "fieldSelector", + "value": "webserver in event.check.subscriptions" + } + ], + "rules": [ + { + "arguments": { + "critical_threshold": 70, + "warning_threshold": 50 + }, + "name": "webservers_50-70", + "template": "aggregate" + } + ], + "services": [ + "website-services" + ] + } +} +{{< /code >}} +{{< /language-toggle >}} + +type | +-------------|------ +description | Top-level attribute that specifies the resource type. For service component configuration, the type should always be `ServiceComponent`. +required | Required for service component configuration in `wrapped-json` or `yaml` format. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +type: ServiceComponent +{{< /code >}} +{{< code json >}} +{ + "type": "ServiceComponent" +} +{{< /code >}} +{{< /language-toggle >}} + +### Metadata attributes + +| annotations | | +-------------|------ +description | Non-identifying metadata to include with observation event data that you can access with [event filters][11]. You can use annotations to add data that's meaningful to people or external tools that interact with Sensu.

    In contrast to labels, you cannot use annotations in [API response filtering][14], [sensuctl response filtering][15], or [web UI views][13]. +required | false +type | Map of key-value pairs. Keys and values can be any valid UTF-8 string. +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +annotations: + managed-by: ops +{{< /code >}} +{{< code json >}} +{ + "annotations": { + "managed-by": "ops" + } +} +{{< /code >}} +{{< /language-toggle >}} + +| created_by | | +-------------|------ +description | Username of the Sensu user who created or last updated the service component. Sensu automatically populates the `created_by` field when the service component is created or updated. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +created_by: admin +{{< /code >}} +{{< code json >}} +{ + "created_by": "admin" +} +{{< /code >}} +{{< /language-toggle >}} + +| labels | | +-------------|------ +description | Custom attributes to include with observation event data that you can use for response and web UI view filtering.

    If you include labels in your event data, you can filter [API responses][14], [sensuctl responses][15], and [web UI views][12] based on them. In other words, labels allow you to create meaningful groupings for your data.

    Limit labels to metadata you need to use for response filtering. For complex, non-identifying metadata that you will *not* need to use in response filtering, use annotations rather than labels. +required | false +type | Map of key-value pairs. Keys can contain only letters, numbers, and underscores and must start with a letter. Values can be any valid UTF-8 string. +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +labels: + region: us-west-1 +{{< /code >}} +{{< code json >}} +{ + "labels": { + "region": "us-west-1" + } +} +{{< /code >}} +{{< /language-toggle >}} + +name | | +-------------|------ +description | Name for the service component that is used internally by Sensu. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +name: webservers +{{< /code >}} +{{< code json >}} +{ + "name": "webservers" +} +{{< /code >}} +{{< /language-toggle >}} + +namespace | | +-------------|------ +description | [Sensu RBAC namespace][7] that the service component belongs to. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +namespace: default +{{< /code >}} +{{< code json >}} +{ + "namespace": "default" +} +{{< /code >}} +{{< /language-toggle >}} + +### Spec attributes + +cron | +-------------|------ +description | When the service component should be executed, using [cron syntax][1] or a [predefined schedule][2]. Use a prefix of `TZ=` or `CRON_TZ=` to set a [timezone][3] for the cron attribute. {{% notice note %}} +**NOTE**: If you're using YAML to create a service component that uses cron scheduling and the first character of the cron schedule is an asterisk (`*`), place the entire cron schedule inside single or double quotes (for example, `cron: '* * * * *'`). +{{% /notice %}} +required | true (unless `interval` is configured) +type | String +example | {{< language-toggle >}} +{{< code yml >}} +cron: 0 0 * * * +{{< /code >}} +{{< code json >}} +{ + "cron": "0 0 * * *" +} +{{< /code >}} +{{< /language-toggle >}} + +handlers | +-------------|------ +description | List of handlers to use for the events the service component produces. The service component will set the handlers property in events that are produced by rule evaluation. If no handlers are specified in the service component definition, handlers can be set by the monitoring rule itself via template arguments. Handlers specified in the service component definition will override any handlers set by rule evaluation. +required | false +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +handlers: + - slack +{{< /code >}} +{{< code json >}} +{ + "handlers": [ + "slack" + ] +} +{{< /code >}} +{{< /language-toggle >}} + +interval | +-------------|------ +description | How often the service component should be executed. In seconds. Each service component must have a value for either the `interval` or the `cron` attribute, but not both. +required | true (unless `cron` is configured) +type | Integer +example | {{< language-toggle >}} +{{< code yml >}} +interval: 60 +{{< /code >}} +{{< code json >}} +{ + "interval": 60 +} +{{< /code >}} +{{< /language-toggle >}} + +query | +-------------|------ +description | Query expression that describes the events that each monitoring rule should process for the service component. Read [query attributes][16] for details. +required | true +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +query: + - type: fieldSelector + value: webserver in event.check.subscriptions +{{< /code >}} +{{< code json >}} +{ + "query": [ + { + "type": "fieldSelector", + "value": "webserver in event.check.subscriptions" + } + ] +} +{{< /code >}} +{{< /language-toggle >}} + +rules | +-------------|------ +description | List of the rule templates and arguments that Sensu should apply for the service component. Sensu evaluates each rule separately, and each rule produces its own event as output. Read [rules attributes][4] for details. +required | true +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +rules: +- arguments: + critical_threshold: 70 + warning_threshold: 50 + name: webservers_50-70 + template: aggregate +{{< /code >}} +{{< code json >}} +{ + "rules": [ + { + "arguments": { + "critical_threshold": 70, + "warning_threshold": 50 + }, + "name": "webservers_50-70", + "template": "aggregate" + } + ] +} +{{< /code >}} +{{< /language-toggle >}} + +services | +-------------|------ +description | List of business [service entities][10] that include the service component as a dependency. +required | true +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +services: + - website-services +{{< /code >}} +{{< code json >}} +{ + "services": [ + "website-services" + ] +} +{{< /code >}} +{{< /language-toggle >}} + +#### Query attributes + +type | +-------------|------ +description | Type of selector to use to identify the events that the service component's monitoring rule should process: `fieldSelector` or `labelSelector`. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +type: fieldSelector +{{< /code >}} +{{< code json >}} +{ + "type": "fieldSelector" +} +{{< /code >}} +{{< /language-toggle >}} + +value | +-------------|------ +description | Selector expression the query will use to identify the events that the service component's monitoring rule should process. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +value: webserver in event.check.subscriptions +{{< /code >}} +{{< code json >}} +{ + "value": "webserver in event.check.subscriptions" +} +{{< /code >}} +{{< /language-toggle >}} + +#### Rules attributes + +arguments | +-------------|------ +description | The arguments to pass to the [rule template][8] for the service component. Argument names and values will vary depending on the arguments configured in the specified rule template. +required | false +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +- arguments: + critical_threshold: 70 + warning_threshold: 50 +{{< /code >}} +{{< code json >}} +{ + "arguments": { + "critical_threshold": 70, + "warning_threshold": 50 + } +} +{{< /code >}} +{{< /language-toggle >}} + +name | +-------------|------ +description | Explicit name to use for the rule-specific events generated for the service component. These names help keep events distinct when a service component includes different rules for the same [rule template][8]. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +name: webservers_50-70 +{{< /code >}} +{{< code json >}} +{ + "name": "webservers_50-70" +} +{{< /code >}} +{{< /language-toggle >}} + +template | +-------------|------ +description | Name of the [rule template][8] the service component should use. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +template: aggregate +{{< /code >}} +{{< code json >}} +{ + "template": "aggregate" +} +{{< /code >}} +{{< /language-toggle >}} + + +[1]: https://en.wikipedia.org/wiki/Cron#CRON_expression +[2]: https://godoc.org/github.com/robfig/cron#hdr-Predefined_schedules +[3]: https://en.wikipedia.org/wiki/Cron#Timezone_handling +[4]: #rules-attributes +[6]: #spec-attributes +[7]: ../../../operations/control-access/namespaces +[8]: ../rule-templates/ +[9]: ../../../commercial/ +[10]: ../../observe-entities/#service-entities +[11]: ../../observe-filter/filters/ +[12]: ../../../web-ui/search#search-for-labels +[13]: ../../../web-ui/search/ +[14]: ../../../api/#response-filtering +[15]: ../../../sensuctl/filter-responses/ +[16]: #query-attributes diff --git a/content/sensu-go/6.12/observability-pipeline/observe-schedule/subscriptions.md b/content/sensu-go/6.12/observability-pipeline/observe-schedule/subscriptions.md new file mode 100644 index 0000000000..37b4f2f71c --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-schedule/subscriptions.md @@ -0,0 +1,202 @@ +--- +title: "Subscriptions reference" +linkTitle: "Subscriptions Reference" +reference_title: "Subscriptions" +type: "reference" +description: "Use Sensu subscriptions to configure checks in a one-to-many model and write checks even if you don't know the names of the entities that should run the checks." +weight: 100 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: observe-schedule +--- + +Sensu uses the [publish/subscribe model of communication][1]. +The publish/subscribe model is powerful in ephemeral or elastic infrastructures, where the names and numbers of things change over time. + +Because Sensu uses the publish/subscribe model, you can write checks even if you don't know the specific names of the entities that should run the checks. +Likewise, your entities do not need to know the specific names of the checks they should execute. +The Sensu backend coordinates check execution for you by comparing the subscriptions you specify in your checks and entities to determine which entities should receive execution requests for a given check. + +The diagram below shows how Sensu coordinates check execution based on subscriptions. +For example, the `check_cpu` check includes the `system` subscription. +All three entities include the `system` subscription, so all three entities will execute the `check_cpu` check. +However, only the `server01` and `database01` entities will execute `check_sshd_process` — the `webserver01` entity does not include the `linux` subscription required to execute `check_sshd_process`. + +{{< figure src="/images/go/subscriptions_reference/subscriptions_diagram.png" alt="Diagram showing example of Sensu check execution based on subscriptions" link="/images/go/subscriptions_reference/subscriptions_diagram.png" target="_blank" >}} + + + +Sensu subscriptions are equivalent to topics in a traditional publish/subscribe system. +Sensu entities become subscribers to these topics via the strings you specify with the agent `subscriptions` flag. +Sensu checks have a `subscriptions` attribute, where you specify strings to indicate which subscribers will execute the checks. +For Sensu to execute a check, the check definition must include a subscription that matches the subscription of at least one Sensu entity. + +{{% notice note %}} +**NOTE**: [Proxy entities](../../observe-entities/entities/#create-and-manage-proxy-entities) do not use subscriptions. +Instead, use [proxy checks](../checks/#proxy-checks) to generate events for proxy entities. +{{% /notice %}} + +As loosely coupled references, subscriptions avoid the fragility of traditional host-based monitoring systems. +Subscriptions allow you to configure check requests in a one-to-many model for entire groups or subgroups of entities rather than a traditional one-to-one mapping of configured hosts or observability checks. + +## Subscription example + +Suppose you have a Sensu agent entity with the `linux` subscription: + +{{< code shell >}} +sensu-agent start --subscriptions linux --log-level debug +{{< /code >}} + +For this agent to run a check, you must have at least one check with `linux` specified in the `subscriptions` attribute, such as this check to collect status information: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: collect_info +spec: + command: collect.sh + handlers: + - slack + interval: 10 + publish: true + subscriptions: + - linux +{{< /code >}} + +{{< code json >}} +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "namespace": "default" + }, + "spec": { + "command": "collect.sh", + "handlers": [ + "slack" + ], + "interval": 10, + "publish": true, + "subscriptions": [ + "linux" + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +If this is your only check for the `linux` subscription, this is the only check that your agent will execute. +If you add more checks that specify the `linux` subscription, your agent will automatically run those checks too (as long as the `publish` attribute is set to `true` in the check definitions). + +You can also add more subscriptions for your entity. +For example, if you want your agent entity to execute checks for the `webserver` subscription, you can add it with the `subscriptions` flag: + +{{< code shell >}} +sensu-agent start --subscriptions linux,webserver --log-level debug +{{< /code >}} + +Now your agent entity will execute checks with the `linux` or `webserver` subscriptions. + +To directly add, update, and delete subscriptions for individual entities, use [sensuctl][17], the [core/v2/entities API endpoints][18], or the [web UI][19]. + +## Configure subscriptions + +Sensu automatically executes a check when the check definition includes a subscription that matches a subscription for at least one Sensu entity. +In other words, subscriptions are configured for both checks and agent entities: + +- To configure subscriptions for a check, add one or more subscription names in the [check `subscriptions` attribute][15]. +- To configure subscriptions for an agent entity, specify a subscription that matches one subscription in each check that the agent's entities should execute. + +The Sensu backend [schedules][13] checks once per interval for each agent entity with a matching subscription. +For example, if you have three entities configured with the `system` subscription, a check configured with the `system` subscription results in three monitoring events per interval: one check execution per entity per interval. + +{{% notice warning %}} +**WARNING**: Make sure that your checks and entities share only one subscription. +Entities receive a separate check request for each matching subscription, even if the requests are for the same check. +This can result in check execution errors as well as unexpected results for check `history` and the features that rely on it. +{{% /notice %}} + +In addition to the subscriptions defined in the agent configuration, Sensu agent entities subscribe automatically to subscriptions that match their [entity `name`][10]. +For example, an agent entity with `name: "i-424242"` subscribes to check requests with the subscription `entity:i-424242`. +This makes it possible to generate ad hoc check requests that target specific entities via the API. + +{{% notice note %}} +**NOTE**: You can directly add, update, and delete subscriptions for individual entities via the backend with [sensuctl](../../../sensuctl/create-manage-resources/#update-resources), the [core/v2/entities API endpoints](../../../api/core/entities/), and the [web UI](../../../web-ui/view-manage-resources/#manage-entities). +{{% /notice %}} + +## Publish checks + +If you want Sensu to automatically schedule and execute a check according to its subscriptions, set the [`publish` attribute][12] to `true` in the check definition. + +You can also manually schedule [ad hoc check execution][11] with the [core/v2/checks API endpoints][16], whether the `publish` attribute is set to `true` or `false`. +To target the subscriptions defined in the check, include only the check name in the request body (for example, `"check": "check_cpu"`). +To override the check's subscriptions and target an alternate entity or group of entities, add the subscriptions attribute to the request body: + +{{< code shell >}} +{ + "check": "check_cpu", + "subscriptions": [ + "entity:i-424242", + "entity:i-828282" + ] +} +{{< /code >}} + +## Monitor multiple servers + +You can use subscriptions to configure monitoring and observability for multiple servers with different operating systems and monitoring requirements. + +For example, suppose you want to set up monitoring for these servers: + +- Six Linux servers: + - Get CPU, memory, and disk status for all six + - Get NGINX metrics for four + - Get PostgreSQL metrics for two + +- Six Windows servers: + - Get CPU, memory, and disk checks for all six + - Get SQL Server metrics for two + +This diagram shows the subscriptions to list for each of the 12 servers (the entities) and for each check to achieve the example monitoring configuration: + +{{< figure src="/images/go/subscriptions_reference/subscriptions_multiple_servers.png" alt="Diagram showing an example of Sensu check execution for multiple server entities based on subscriptions" link="/images/go/subscriptions_reference/subscriptions_multiple_servers.png" target="_blank" >}} + + + +In this scenario, none of the Windows servers should execute the NGINX metrics check, so the `check_nginx` subscriptions do not match any subscriptions listed for any of the Windows servers. +Two of the six Windows servers *should* execute the SQL Server metrics check, so the subscription listed in the `check_sqlsrv` definition matches a subscription listed for those two Windows server entities. + +## Subscription naming considerations + +Consistent subscription naming helps you group and filter different entities and quickly understand which entities will be affected by any changes. + +Subscriptions based on function are helpful when you're creating silences. +For example, if you need to silence all webservers for maintenance, it's easier to silence the affected entities if they all include a subscription like `webserver` instead of identifying and silencing all of your webserver entities individually. +Other function-based subscriptions might be `database`, `switch`, `service`, or `container`. + +Subscription naming is also important in the context of API and sensuctl filters and web UI searches. +Consistent subscription naming means that search queries like `"linux" in checks.subscriptions` will actually retrieve all of your checks that run on Linux agents. + +To make subscriptions more granular, use camel case to append information about environment, roles, entity type, or any other category as needed. +For example, you can use `webserverDev` and `webserverProd` to specify a distinction between development and production webservers while preserving your ability to find all webserver entities with a search query like `"webserver" in entity.subscriptions`. + + +[1]: https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern +[2]: ../agent/#subscriptions-option +[10]: ../agent/#name-attribute +[11]: ../checks/#ad-hoc-scheduling +[12]: ../checks/#publish-attribute +[13]: ../checks/#check-scheduling +[15]: ../checks/#check-subscriptions +[16]: ../../../api/core/checks/#checkscheckexecute-post +[17]: ../../../sensuctl/create-manage-resources/#update-resources +[18]: ../../../api/core/entities/ +[19]: ../../../web-ui/view-manage-resources/#manage-entities diff --git a/content/sensu-go/6.12/observability-pipeline/observe-schedule/tokens.md b/content/sensu-go/6.12/observability-pipeline/observe-schedule/tokens.md new file mode 100644 index 0000000000..a0871a8540 --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-schedule/tokens.md @@ -0,0 +1,347 @@ +--- +title: "Tokens reference" +linkTitle: "Tokens Reference" +reference_title: "Tokens" +type: "reference" +description: "Use tokens in Sensu checks as placeholders that agents replace with entity data to fine-tune check attributes while reusing check definitions." +weight: 120 +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: observe-schedule +--- + +Tokens are placeholders in a check definition that the agent replaces with entity information before executing the check. +You can use tokens to fine-tune check attributes (like alert thresholds) on a per-entity level while reusing the check definition. + +When a check is scheduled to be executed by an agent, it first goes through a token substitution step. +The agent replaces any tokens with matching attributes from the entity definition, and then the check is executed. +Invalid templates or unmatched tokens return an error, which is logged and sent to the Sensu backend message transport. +Checks with token-matching errors are not executed. + +Token substitution is supported for [check][7], [hook][8], and [dynamic runtime asset][12] definitions. +Only [entity attributes][4] are available for substitution. +Token substitution is not available for event filters because filters already have access to the entity. + +Available entity attributes will always have [string values][9], such as labels and annotations. + +## Example: Token substitution for check thresholds + +This example demonstrates a reusable disk usage check. +The [check command][5] includes `-w` (warning) and `-c` (critical) arguments with default values for the thresholds (as percentages) for generating warning or critical events. +The check will compare every subscribed entity's disk space against the default threshold values to determine whether to generate a warning or critical event. + +However, the check command also includes token substitution, which means you can add entity labels that correspond to the check command tokens to specify different warning and critical values for individual entities. +Instead of creating a different check for every set of thresholds, you can use the same check to apply the defaults in most cases and the token-substituted values for specific entities. + +Follow this example to set up a reusable check for disk usage: + +1. Add the [sensu/check-disk-usage][13] dynamic runtime asset, which includes the command you will need for your check: +{{< code shell >}} +sensuctl asset add sensu/check-disk-usage:0.6.0 +{{< /code >}} + + You will receive a response to confirm that the asset was added: +{{< code text >}} +fetching bonsai asset: sensu/check-disk-usage:0.6.0 +added asset: sensu/check-disk-usage:0.6.0 + +You have successfully added the Sensu asset resource, but the asset will not get downloaded until +it's invoked by another Sensu resource (ex. check). To add this runtime asset to the appropriate +resource, populate the "runtime_assets" field with ["sensu/check-disk-usage]. +{{< /code >}} + +2. Create the `check-disk-usage` check: +{{< language-toggle >}} +{{< code shell "YML" >}} +cat << EOF | sensuctl create +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: check-disk-usage +spec: + check_hooks: [] + command: check-disk-usage -w {{index .labels "disk_warning" | default 80}} -c + {{.labels.disk_critical | default 90}} + env_vars: null + handlers: [] + high_flap_threshold: 0 + interval: 10 + low_flap_threshold: 0 + output_metric_format: "" + output_metric_handlers: null + output_metric_tags: null + proxy_entity_name: "" + publish: true + round_robin: false + runtime_assets: + - sensu/check-disk-usage + stdin: false + subdue: null + subscriptions: + - system + timeout: 0 + ttl: 0 +EOF +{{< /code >}} +{{< code shell "JSON" >}} +cat << EOF | sensuctl create +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "check-disk-usage" + }, + "spec": { + "check_hooks": [], + "command": "check-disk-usage -w {{index .labels "disk_warning" | default 80}} -c {{.labels.disk_critical | default 90}}", + "env_vars": null, + "handlers": [], + "high_flap_threshold": 0, + "interval": 10, + "low_flap_threshold": 0, + "output_metric_format": "", + "output_metric_handlers": null, + "output_metric_tags": null, + "proxy_entity_name": "", + "publish": true, + "round_robin": false, + "runtime_assets": [ + "sensu/check-disk-usage" + ], + "stdin": false, + "subdue": null, + "subscriptions": [ + "system" + ], + "timeout": 0, + "ttl": 0 + } +} +EOF +{{< /code >}} +{{< /language-toggle >}} + + This check will run on every entity with the subscription `system`. +According to the default values in the command, the check will generate a warning event at 80% disk usage and a critical event at 90% disk usage. + +3. To receive alerts at different thresholds for an existing entity with the `system` subscription, add `disk_warning` and `disk_critical` labels to the entity. + + Use sensuctl to open an existing entity in a text editor: +{{< code shell >}} +sensuctl edit entity ENTITY_NAME +{{< /code >}} + + And add the following labels in the entity metadata: +{{< code yml >}} + labels: + disk_warning: "65" + disk_critical: "75" +{{< /code >}} + +After you save your changes, the `check-disk-usage` check will substitute the `disk_warning` and `disk_critical` label values to generate events at 65% and 75% of disk usage, respectively, for this entity only. +The check will continue to use the 80% and 90% default values for other subscribed entities. + +### Add a hook that uses token substitution + +Now you have a resusable check that will send disk usage alerts at default or entity-specific thresholds. +You may want to add a [hook][8] to list more details about disk usage for warning and critical events. + +The hook in this example will list disk usage in human-readable format, with error messages filtered from the hook output. +By default, the hook will list details for the top directory and the first layer of subdirectories. +As with the `check-disk-usage` check, you can add a `disk_usage_root` label to individual entities to specify a different directory for the hook via token substitution. + +1. Add the hook definition: +{{< language-toggle >}} +{{< code shell "YML" >}} +cat << EOF | sensuctl create +--- +type: HookConfig +api_version: core/v2 +metadata: + name: disk_usage_details +spec: + command: du -h --max-depth=1 -c {{index .labels "disk_usage_root" | default "/"}} 2>/dev/null + runtime_assets: null + stdin: false + timeout: 60 +EOF +{{< /code >}} +{{< code shell "JSON" >}} +cat << EOF | sensuctl create +{ + "type": "HookConfig", + "api_version": "core/v2", + "metadata": { + "name": "disk_usage_details" + }, + "spec": { + "command": "du -h --max-depth=1 -c {{index .labels "disk_usage_root" | default \"/\"}} 2>/dev/null", + "runtime_assets": null, + "stdin": false, + "timeout": 60 + } +} +EOF +{{< /code >}} +{{< /language-toggle >}} + +2. Add the hook to the `check-disk-usage` check. + + Use sensuctl to open the check in a text editor: +{{< code shell >}} +sensuctl edit check check-disk-usage +{{< /code >}} + + Update the check definition to include the `disk_usage_details` hook for `non-zero` events: +{{< code yml >}} + check_hooks: + - non-zero: + - disk_usage_details +{{< /code >}} + +3. As with the disk usage check command, the hook command includes a token substitution option. +To use a specific directory instead of the default for specific entities, edit the entity definition to add a `disk_usage_root` label and specify the directory: + + Use sensuctl to open the entity in a text editor: +{{< code shell >}} +sensuctl edit entity ENTITY_NAME +{{< /code >}} + + Add the `disk_usage_root` label with the desired substitute directory in the entity metadata: +{{< code yml >}} + labels: + disk_usage_root: "/substitute-directory" +{{< /code >}} + +After you save your changes, for this entity, the hook will substitute the directory you specified for the `disk_usage_root` label to provide additional disk usage details for every non-zero event the `check-disk-usage` check generates. + +## Manage entity labels + +You can use token substitution with any defined [entity attributes][4], including custom labels. +read the [entities reference][6] for information about managing entity labels for proxy entities and agent entities. + +## Manage dynamic runtime assets + +You can use token substitution in the URLs of your your [dynamic runtime asset][12] definitions. +Token substitution allows you to host your dynamic runtime assets at different URLs (such as at different datacenters) without duplicating your assets, as shown in the following example: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Asset +api_version: core/v2 +metadata: + name: sensu-go-hello-world +spec: + builds: + - sha512: 07665fda5b7c75e15e4322820aa7ddb791cc9338e38444e976e601bc7d7970592e806a7b88733690a238b7325437d31f85e98ae2fe47b008ca09c86530da9600 + url: "{{ .labels.asset_url }}/sensu-go-hello-world-0.0.1.tar.gz" +{{< /code >}} + +{{< code json >}} +{ + "type": "Asset", + "api_version": "core/v2", + "metadata": { + "name": "sensu-go-hello-world" + }, + "spec": { + "builds": [ + { + "sha512": "07665fda5b7c75e15e4322820aa7ddb791cc9338e38444e976e601bc7d7970592e806a7b88733690a238b7325437d31f85e98ae2fe47b008ca09c86530da9600", + "url": "{{ .labels.asset_url }}/sensu-go-hello-world-0.0.1.tar.gz" + } + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +With this asset definition, which includes the `.labels.asset_url` token substitution, checks and hooks can include `sensu-go-hello-world` as a dynamic runtime assets and Sensu Go will use the token substitution for the agent's entity. +Handlers and mutators can also include `sensu-go-hello-world` as a dynamic runtime asset, but Sensu Go will use the token subtitution for the backend's entity instead of the agent's entity. + +You can also use token substitution to customize dynamic runtime asset headers (for example, to include secure information for authentication). +Sensu also provides an [`assetPath` function][14] that allows you to substitute a dynamic runtime asset’s local path on disk. + +{{% notice note %}} +**NOTE**: To maintain security, you cannot use token substitution for a dynamic runtime asset's SHA512 value. +{{% /notice %}} + +## Token specification + +Sensu Go uses the [Go template][1] package to implement token substitution. +Use double curly braces around the token and a dot before the attribute to be substituted: `{{ .system.hostname }}`. + +### Token substitution syntax + +Tokens are invoked by wrapping references to entity attributes and labels with double curly braces, such as `{{ .name }}` to substitute an entity's name. +Access nested Sensu [entity attributes][3] with dot notation (for example, `system.arch`). + +- `{{ .name }}` would be replaced with the [entity `name` attribute][3] +- `{{ .labels.url }}` would be replaced with a custom label called `url` +- `{{ .labels.disk_warning }}` would be replaced with a custom label called `disk_warning` +- `{{ index .labels "disk_warning" }}` would be replaced with a custom label called + `disk_warning` +- `{{ index .labels "cpu.threshold" }}` would be replaced with a custom label called `cpu.threshold` + +{{% notice note %}} +**NOTE**: When an annotation or label name has a dot (for example, `cpu.threshold`), you must use the template index function syntax to ensure correct processing because the dot notation is also used for object nesting. +{{% /notice %}} + +### Token substitution default values + +If an attribute is not provided by the [entity][3], a token's default value will be substituted. +Token default values are separated by a pipe character and the word "default" (`| default`). +Use token default values to provide a fallback value for entities that are missing a specified token attribute. + +For example, `{{.labels.url | default "https://sensu.io"}}` would be replaced with a custom label called `url`. +If no such attribute called `url` is included in the entity definition, the default (or fallback) value of `https://sensu.io` will be used to substitute the token. + +### Token substitution with quoted strings + +You can escape quotes to express quoted strings in token substitution templates as shown in the [Go template package examples][2]. +For example, to provide `"substitution"` as a default value for entities that are missing the `website` attribute (including the quotation marks): + +{{< code shell >}} +{{ .labels.website | default "\"substitution\"" }} +{{< /code >}} + +## Unmatched tokens + +If a token is unmatched during check preparation, the agent check handler will return an error, and the check will not be executed. +Unmatched token errors are similar to this example: + +{{< code text >}} +error: unmatched token: template: :1:22: executing "" at <.system.hostname>: map has no entry for key "System" +{{< /code >}} + +Check config token errors are logged by the agent and sent to Sensu backend message transport as check failures. + +## Token data type limitations + +As part of the substitution process, Sensu converts all tokens to strings. +This means that token substitution cannot be applied to any non-string values like numbers or Booleans, although it can be applied to strings that are nested inside objects and arrays. + +For example, token substitution **cannot** be used for specifying a check interval because the interval attribute requires an _integer_ value. +Token substitution **can** be used for alerting thresholds because those values are included within the command _string_. + + +[1]: https://pkg.go.dev/text/template +[2]: https://pkg.go.dev/text/template?tab=doc#hdr-Examples +[3]: ../../observe-entities/entities/#entities-specification +[4]: ../../observe-entities/entities/ +[5]: ../checks/#check-commands +[6]: ../../observe-entities/entities#manage-entity-labels +[7]: ../checks/#check-commands +[8]: ../hooks/ +[9]: #token-data-type-limitations +[10]: ../../observe-process/handlers/ +[11]: ../../observe-transform/mutators/ +[12]: ../../../plugins/assets/ +[13]: https://bonsai.sensu.io/assets/sensu/check-disk-usage +[14]: ../../../plugins/assets/#assetpath-function-for-dynamic-runtime-asset-paths diff --git a/content/sensu-go/6.12/observability-pipeline/observe-transform/_index.md b/content/sensu-go/6.12/observability-pipeline/observe-transform/_index.md new file mode 100644 index 0000000000..05ed32717d --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-transform/_index.md @@ -0,0 +1,128 @@ +--- +title: "Transform your observation data" +linkTitle: "Transform" +description: "Learn how the transform stage of the Sensu observability pipeline works to mutate your observation data into a format that other technologies can consume." +product: "Sensu Go" +version: "6.12" +weight: 60 +layout: "single" +toc: true +menu: + sensu-go-6.12: + parent: observability-pipeline + identifier: observe-transform +--- + + + + +** or click any element in the pipeline to jump to it.** + +**In the transform stage, Sensu executes [mutators][1]**. + +The transform stage of the Sensu observability pipeline executes any [mutators][1] you have specified in your [pipeline][2] configuration to transform your observability data so other technologies can consume it. +For example, if you're sending metrics to Graphite using a TCP handler, Graphite expects data that follows the Graphite plaintext protocol. +You can use Sensu's [built-in only_check_output mutator][4] to transform the data into the format Graphite can accept. + +Here's how transform stage of the pipeline works: first, the Sensu backend receives an event and executes the [filter][3] stage of the observability pipeline. +If the event data meets the conditions, triggers, or thresholds you specified in your event filters, Sensu checks the pipeline for a mutator. +If the pipeline includes a mutator, the Sensu backend executes the mutator. + +There are two types of mutators: [pipe][8] and [JavaScript][9]. + +## Pipe mutators + +[Pipe mutator][10] definitions include executable commands that will be executed on a Sensu backend. +Pipe mutators produce an exit status code to indicate state. + +* If the mutator executes successfully (that is, returns an exit status code of `0`), Sensu applies the mutator to transform the event data, returns the transformed event data to the handler specified in the pipeline, and executes the handler. +* If the mutator fails to execute (that is, returns a non-zero exit status code or fails to complete within its configured timeout), Sensu logs an error and does not execute the handler specified in the pipeline. + +This example pipe mutator resource definition uses the [Sensu Check Status Metric Mutator][7] dynamic runtime asset: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Mutator +api_version: core/v2 +metadata: + name: sensu-check-status-metric-mutator +spec: + command: sensu-check-status-metric-mutator + runtime_assets: + - nixwiz/sensu-check-status-metric-mutator +{{< /code >}} + +{{< code json >}} +{ + "type": "Mutator", + "api_version": "core/v2", + "metadata": { + "name": "sensu-check-status-metric-mutator" + }, + "spec": { + "command": "sensu-check-status-metric-mutator", + "runtime_assets": [ + "nixwiz/sensu-check-status-metric-mutator" + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +Most pipe mutator commands are provided by Sensu plugins, which you can deploy with dynamic runtime assets. +Use [Bonsai][5], the Sensu asset hub, to discover, download, and share dynamic runtime assets for Sensu pipe mutators. +Read [Use assets to install plugins][6] to get started. + +## JavaScript mutators + +[JavaScript mutators][11] allow you to write your own evaluation expressions and do not require an executable command attribute. +Each Sensu JavaScript mutator definition includes the eval attribute, whose value must be an ECMAScript 5 expression. + +This example uses a JavaScript mutator to remove event attributes (in this case, the check name and entity `app_id` label): + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Mutator +api_version: core/v2 +metadata: + name: remove_checkname_entitylabel +spec: + eval: >- + data = JSON.parse(JSON.stringify(event)); delete data.check.metadata.name; + delete data.entity.metadata.labels.app_id; return JSON.stringify(data) + type: javascript +{{< /code >}} + +{{< code json >}} +{ + "type": "Mutator", + "api_version": "core/v2", + "metadata": { + "name": "remove_checkname_entitylabel" + }, + "spec": { + "eval": "data = JSON.parse(JSON.stringify(event)); delete data.check.metadata.name; delete data.entity.metadata.labels.app_id; return JSON.stringify(data)", + "type": "javascript" + } +} +{{< /code >}} + +{{< /language-toggle >}} + + +[1]: mutators/ +[2]: ../observe-process/pipelines/ +[3]: ../observe-filter/ +[4]: mutators/#built-in-mutator-only_check_output +[5]: https://bonsai.sensu.io/ +[6]: ../../plugins/use-assets-to-install-plugins/ +[7]: https://bonsai.sensu.io/assets/nixwiz/sensu-check-status-metric-mutator +[8]: #pipe-mutators +[9]: #javascript-mutators +[10]: mutators/#pipe-mutators +[11]: mutators/#javascript-mutators diff --git a/content/sensu-go/6.12/observability-pipeline/observe-transform/mutators.md b/content/sensu-go/6.12/observability-pipeline/observe-transform/mutators.md new file mode 100644 index 0000000000..2cc0f561cd --- /dev/null +++ b/content/sensu-go/6.12/observability-pipeline/observe-transform/mutators.md @@ -0,0 +1,805 @@ +--- +title: "Mutators reference" +linkTitle: "Mutators Reference" +reference_title: "Mutators" +type: "reference" +description: "As part of the event pipeline, mutators let you transform observability event data before applying handlers. Read the reference doc to learn about mutators." +product: "Sensu Go" +weight: 10 +version: "6.12" +platformContent: false +menu: + sensu-go-6.12: + parent: observe-transform +--- + +Sensu executes mutators during the **[transform][16]** stage of the [observability pipeline][17]. + +[Pipelines][27] can specify a mutator to execute and transform observability event data before any handlers are applied. +When the Sensu backend processes an event, it checks the pipeline for the presence of a mutator and executes that mutator before executing the handler. + +Mutators accept input/data via stdin and can parse JSON event data. +They output JSON data (modified event data) to stdout or stderr. + +There are two types of mutators: [pipe][21] and [JavaScript][18]. + +## Pipe mutator examples + +This example shows a [pipe mutator][21] resource definition with the minimum required attributes: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Mutator +api_version: core/v2 +metadata: + name: mutator_minimum +spec: + command: example_mutator.go + type: pipe +{{< /code >}} + +{{< code json >}} +{ + "type": "Mutator", + "api_version": "core/v2", + "metadata": { + "name": "mutator_minimum" + }, + "spec": { + "command": "example_mutator.go", + "type": "pipe" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +The following mutator definition uses an imaginary Sensu plugin, `example_mutator.go`, to modify event data prior to handling the event: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Mutator +api_version: core/v2 +metadata: + name: example-mutator +spec: + command: example_mutator.go + eval: "" + env_vars: [] + runtime_assets: + - example-mutator-asset + secrets: null + timeout: 0 + type: pipe +{{< /code >}} + +{{< code json >}} +{ + "type": "Mutator", + "api_version": "core/v2", + "metadata": { + "name": "example-mutator" + }, + "spec": { + "command": "example_mutator.go", + "timeout": 0, + "env_vars": [], + "runtime_assets": [ + "example-mutator-asset" + ], + "secrets": null, + "type": "pipe", + "eval": "" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## JavaScript mutator example + +[JavaScript mutators][18] use the eval attribute instead of the command attribute. +The eval value must be an ECMAScript 5 (JavaScript) expression. + +This example uses a JavaScript mutator to remove event attributes that are not required — in this case, the check name and entity `app_id` label: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Mutator +api_version: core/v2 +metadata: + name: remove_checkname_entitylabel +spec: + eval: >- + data = JSON.parse(JSON.stringify(event)); delete data.check.metadata.name; + delete data.entity.metadata.labels.app_id; return JSON.stringify(data) + type: javascript +{{< /code >}} + +{{< code json >}} +{ + "type": "Mutator", + "api_version": "core/v2", + "metadata": { + "name": "remove_checkname_entitylabel" + }, + "spec": { + "eval": "data = JSON.parse(JSON.stringify(event)); delete data.check.metadata.name; delete data.entity.metadata.labels.app_id; return JSON.stringify(data)", + "type": "javascript" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +You can also use JavaScript mutators to do things like [add new attributes][23] and [combine existing attributes into a single new attribute][24]. + +## Pipe mutators + +**Pipe mutators** produce an exit status code to indicate state. +A code of `0` indicates OK status. +If the mutator executes successfully (returns an exit status code of `0`), the modified event data return to the pipeline and the handler is executed. + +Exit codes other than `0` indicate failure. +If the mutator fails to execute (returns a non-zero exit status code or fails to complete within its configured timeout), an error is logged and the handler will not execute. + +### Pipe mutator commands + +Each Sensu mutator definition defines a command to be executed. +Mutator commands are executable commands that will be executed on a Sensu backend, run as the `sensu` user. +Most mutator commands are provided by [Sensu plugins][4]. + +Sensu mutator `command` attributes may include command line arguments for controlling the behavior of the `command` executable. +Many Sensu mutator plugins provide support for command line arguments for reusability. + +All mutator commands are executed by a Sensu backend as the `sensu` user. +Commands must be executable files that are discoverable on the Sensu backend system (installed in a system `$PATH` directory). + +{{% notice note %}} +**NOTE**: By default, Sensu installer packages will modify the system `$PATH` for the Sensu processes to include `/etc/sensu/plugins`. +As a result, executable scripts (like plugins) located in `/etc/sensu/plugins` will be valid commands. +This allows `command` attributes to use “relative paths” for Sensu plugin commands (for example, `"command": "check-http.go -u https://sensuapp.org"`). +{{% /notice %}} + +## JavaScript mutators + +Mutators that use JavaScript are an efficient alternative to pipe mutators, which fork a process on each invocation. +JavaScript mutators are evaluated by the [Otto JavaScript VM][19] as JavaScript programs, which enables greater mutator throughput at scale. + +JavaScript mutators do not require you to return any value — you can mutate the events that are passed to the mutator instead. +However, if you do return a value with a JavaScript mutator, it must be a string. +If a JavaScript mutator returns a non-string value (an array, object, integer, or Boolean), an error is recorded in the [Sensu backend log][20]. + +JavaScript mutators can use dynamic runtime assets as long as they are valid JavaScript assets. + +Secrets are not available to JavaScript mutators. +JavaScript mutators cannot look up events from the event store. + +### JavaScript mutator eval attribute + +Each Sensu JavaScript mutator definition includes the [eval attribute][22], whose value must be an ECMAScript 5 (JavaScript) expression. +JavaScript mutators do not use the command attribute. + +All mutator eval expressions are executed by a Sensu backend as the `sensu` user. + +JavaScript mutator eval expressions can use the environment variables listed in the [env_vars attribute][25]. +For JavaScript mutators, you can define environment variables and list the names of any environment variables that are available in your environment in the env_vars attribute. + +## Built-in mutators + +Sensu includes built-in mutators to help you customize event pipelines for metrics and alerts. + +### Built-in mutator: only_check_output + +To process an event, some handlers require only the check output, not the entire event definition. +For example, when sending metrics to Graphite using a TCP handler, Graphite expects data that follows the Graphite plaintext protocol. +By using the built-in `only_check_output` mutator, Sensu reduces the event to only the check output so Graphite can accept it. + +To use only check output, include the `only_check_output` mutator in the pipeline `mutator` array: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Pipeline +api_version: core/v2 +metadata: + name: graphite_pipeline +spec: + workflows: + - name: graphite_check_output + filters: + - name: has_metrics + type: EventFilter + api_version: core/v2 + mutator: + name: only_check_output + type: Mutator + api_version: core/v2 + handler: + name: graphite + type: Handler + api_version: core/v2 +{{< /code >}} + +{{< code json >}} +{ + "type": "Pipeline", + "api_version": "core/v2", + "metadata": { + "name": "graphite_pipeline" + }, + "spec": { + "workflows": [ + { + "name": "graphite_check_output", + "filters": [ + { + "name": "has_metrics", + "type": "EventFilter", + "api_version": "core/v2" + } + ], + "mutator": { + "name": "only_check_output", + "type": "Mutator", + "api_version": "core/v2" + }, + "handler": { + "name": "graphite", + "type": "Handler", + "api_version": "core/v2" + } + } + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Mutator specification + +### Top-level attributes + +api_version | +-------------|------ +description | Top-level attribute that specifies the Sensu API group and version. For mutators in this version of Sensu, the `api_version` should always be `core/v2`. +required | Required for mutator definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][5]. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +api_version: core/v2 +{{< /code >}} +{{< code json >}} +{ + "api_version": "core/v2" +} +{{< /code >}} +{{< /language-toggle >}} + +metadata | +-------------|------ +description | Top-level collection of metadata about the mutator that includes `name`, `namespace`, and `created_by` as well as custom `labels` and `annotations`. The `metadata` map is always at the top level of the mutator definition. This means that in `wrapped-json` and `yaml` formats, the `metadata` scope occurs outside the `spec` scope. Review the [metadata attributes reference][2] for details. +required | Required for mutator definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][5]. +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +metadata: + name: example-mutator + namespace: default + created_by: admin + labels: + region: us-west-1 + annotations: + slack-channel: "#monitoring" +{{< /code >}} +{{< code json >}} +{ + "metadata": { + "name": "example-mutator", + "namespace": "default", + "created_by": "admin", + "labels": { + "region": "us-west-1" + }, + "annotations": { + "slack-channel": "#monitoring" + } + } +} +{{< /code >}} +{{< /language-toggle >}} + +spec | +-------------|------ +description | Top-level map that includes the mutator [spec attributes][6]. +required | Required for mutator definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][5]. +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +spec: + command: example_mutator.go + timeout: 0 + env_vars: [] + runtime_assets: [] + secrets: null + type: pipe +{{< /code >}} +{{< code json >}} +{ + "spec": { + "command": "example_mutator.go", + "timeout": 0, + "env_vars": [], + "runtime_assets": [], + "secrets": null, + "type": "pipe" + } +} +{{< /code >}} +{{< /language-toggle >}} + +type | +-------------|------ +description | Top-level attribute that specifies the [`sensuctl create`][5] resource type. Mutators should always be type `Mutator`. +required | Required for mutator definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][5]. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +type: Mutator +{{< /code >}} +{{< code json >}} +{ + "type": "Mutator" +} +{{< /code >}} +{{< /language-toggle >}} + +### Metadata attributes + +| annotations | | +-------------|------ +description | Non-identifying metadata to include with event data that you can access with [event filters][12]. You can use annotations to add data that's meaningful to people or external tools that interact with Sensu.

    In contrast to labels, you cannot use annotations in [API response filtering][8], [sensuctl response filtering][9], or [web UI views][15]. +required | false +type | Map of key-value pairs. Keys and values can be any valid UTF-8 string. +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +annotations: + managed-by: ops + playbook: www.example.url +{{< /code >}} +{{< code json >}} +{ + "annotations": { + "managed-by": "ops", + "playbook": "www.example.url" + } +} +{{< /code >}} +{{< /language-toggle >}} + +| created_by | | +-------------|------ +description | Username of the Sensu user who created the mutator or last updated the mutator. Sensu automatically populates the `created_by` field when the mutator is created or updated. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +created_by: admin +{{< /code >}} +{{< code json >}} +{ + "created_by": "admin" +} +{{< /code >}} +{{< /language-toggle >}} + +| labels | | +-------------|------ +description | Custom attributes to include with event data that you can use for response and web UI view filtering.

    If you include labels in your event data, you can filter [API responses][8], [sensuctl responses][9], and [web UI views][13] based on them. In other words, labels allow you to create meaningful groupings for your data.

    Limit labels to metadata you need to use for response filtering. For complex, non-identifying metadata that you will *not* need to use in response filtering, use annotations rather than labels. +required | false +type | Map of key-value pairs. Keys can contain only letters, numbers, and underscores and must start with a letter. Values can be any valid UTF-8 string. +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +labels: + environment: development + region: us-west-2 +{{< /code >}} +{{< code json >}} +{ + "labels": { + "environment": "development", + "region": "us-west-2" + } +} +{{< /code >}} +{{< /language-toggle >}} + +| name | | +-------------|------ +description | Unique string used to identify the mutator. Mutator names cannot contain special characters or spaces (validated with Go regex [`\A[\w\.\-]+\z`][7]). Each mutator must have a unique name within its namespace. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +name: example-mutator +{{< /code >}} +{{< code json >}} +{ + "name": "example-mutator" +} +{{< /code >}} +{{< /language-toggle >}} + +| namespace | | +-------------|------ +description | Sensu [RBAC namespace][3] that the mutator belongs to. +required | false +type | String +default | `default` +example | {{< language-toggle >}} +{{< code yml >}} +namespace: production +{{< /code >}} +{{< code json >}} +{ + "namespace": "production" +} +{{< /code >}} +{{< /language-toggle >}} + +### Spec attributes + +command | +-------------|------ +description | Mutator command to be executed by the Sensu backend.{{% notice note %}} +**NOTE**: [JavaScript mutators](#javascript-mutators) require the [eval attribute](#eval-attribute) instead of the command attribute. +{{% /notice %}} +required | true, for pipe mutators +type | String +example | {{< language-toggle >}} +{{< code yml >}} +command: /etc/sensu/plugins/mutated.go +{{< /code >}} +{{< code json >}} +{ + "command": "/etc/sensu/plugins/mutated.go" +} +{{< /code >}} +{{< /language-toggle >}} + + + +env_vars | +-------------|------ +description | Array of environment variables to use with command or eval expression execution. +required | false +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +env_vars: +- APP_VERSION=2.5.0 +{{< /code >}} +{{< code json >}} +{ + "env_vars": [ + "APP_VERSION=2.5.0" + ] +} +{{< /code >}} +{{< /language-toggle >}}
    As of [Sensu Go 6.5.2][26], for JavaScript mutators, you can list any environment variables that are available in your environment in addition to defining environment variables:

    {{< language-toggle >}} +{{< code yml >}} +env_vars: +- APP_VERSION=2.5.0 +- SHELL +{{< /code >}} +{{< code json >}} +{ + "env_vars": [ + "APP_VERSION=2.5.0", + "SHELL" + ] +} +{{< /code >}} +{{< /language-toggle >}} + + + +eval | +-------------|------ +description | ECMAScript 5 (JavaScript) expression to be executed by the Sensu backend.{{% notice note %}} +**NOTE**: Pipe mutators require the [command attribute](#spec-attributes) instead of the eval attribute. +{{% /notice %}} +required | true, for [JavaScript mutators][18] +type | String +example | {{< language-toggle >}} +{{< code yml >}} +eval: 'return JSON.stringify({"some stuff": "is here"});' +{{< /code >}} +{{< code json >}} +{ + "eval": "return JSON.stringify({\"some info\": \"is here\"});" +} +{{< /code >}} +{{< /language-toggle >}} + +runtime_assets | +---------------|------ +description | Array of [Sensu dynamic runtime assets][1] (by their names) required at runtime for execution of the `command`. +required | false +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +runtime_assets: +- metric-mutator +{{< /code >}} +{{< code json >}} +{ + "runtime_assets": [ + "metric-mutator" + ] +} +{{< /code >}} +{{< /language-toggle >}} + +secrets | +---------------|------ +description | Array of the name/secret pairs to use with command execution. +required | false +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +secrets: +- name: ANSIBLE_HOST + secret: sensu-ansible-host +- name: ANSIBLE_TOKEN + secret: sensu-ansible-token +{{< /code >}} +{{< code json >}} +{ + "secrets": [ + { + "name": "ANSIBLE_HOST", + "secret": "sensu-ansible-host" + }, + { + "name": "ANSIBLE_TOKEN", + "secret": "sensu-ansible-token" + } + ] +} +{{< /code >}} +{{< /language-toggle >}} + +timeout | +-------------|------ +description | Mutator execution duration timeout (hard stop). In seconds.{{% notice warning %}} +**WARNING**: The timeout attribute is available for [JavaScript mutators](#javascript-mutators) but may not work properly if the mutator is in a loop. +{{% /notice %}} +required | false +type | integer +example | {{< language-toggle >}} +{{< code yml >}} +timeout: 30 +{{< /code >}} +{{< code json >}} +{ + "timeout": 30 +} +{{< /code >}} +{{< /language-toggle >}} + +type | +-------------|------ +description | Mutator type.{{% notice note %}}**NOTE**: Make sure to specify the type is `javascript` when you create a JavaScript mutator. If you do not specify the type, Sensu uses `pipe` as the default, expects a command attribute in the mutator definition, and ignores any eval attribute you provide. +{{% /notice %}} +required | false +type | String +default | `pipe` +allowed values | `pipe` and `javascript` +example | {{< language-toggle >}} +{{< code yml >}} +type: pipe +{{< /code >}} +{{< code json >}} +{ + "type": "pipe" +} +{{< /code >}} +{{< /language-toggle >}} + +#### `secrets` attributes + +name | +-------------|------ +description | Name of the [secret][10] defined in the executable command. Becomes the environment variable presented to the mutator. Read [Use secrets management in Sensu][14] for more information. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +name: ANSIBLE_HOST +{{< /code >}} +{{< code json >}} +{ + "name": "ANSIBLE_HOST" +} +{{< /code >}} +{{< /language-toggle >}} + +secret | +-------------|------ +description | Name of the Sensu secret resource that defines how to retrieve the [secret][10]. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +secret: sensu-ansible-host +{{< /code >}} +{{< code json >}} +{ + "secret": "sensu-ansible-host" +} +{{< /code >}} +{{< /language-toggle >}} + +## Use secrets management in a mutator + +Learn more about [secrets management][14] for your Sensu configuration in the [secrets][10] and [secrets providers][11] references. + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Mutator +api_version: core/v2 +metadata: + name: ansible-tower + namespace: ops +spec: + command: sensu-ansible-mutator -h $ANSIBLE_HOST -t $ANSIBLE_TOKEN + secrets: + - name: ANSIBLE_HOST + secret: sensu-ansible-host + - name: ANSIBLE_TOKEN + secret: sensu-ansible-token +{{< /code >}} + +{{< code json >}} +{ + "type": "Mutator", + "api_version": "core/v2", + "metadata": { + "name": "ansible-tower", + "namespace": "ops" + }, + "spec": { + "command": "sensu-ansible-mutator -h $ANSIBLE_HOST -t $ANSIBLE_TOKEN", + "secrets": [ + { + "name": "ANSIBLE_HOST", + "secret": "sensu-ansible-host" + }, + { + "name": "ANSIBLE_TOKEN", + "secret": "sensu-ansible-token" + } + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Add new event attributes with JavaScript mutators + +Use a JavaScript mutator to rewrite events with a new attribute added. + +This example adds a new "organization" attribute to events at the top level, with a value of `sec_ops`: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Mutator +api_version: core/v2 +metadata: + name: add_org_sec_ops +spec: + eval: >- + data = JSON.parse(JSON.stringify(event)); data['organization'] = 'sec_ops'; + return JSON.stringify(data) + type: javascript +{{< /code >}} + +{{< code json >}} +{ + "type": "Mutator", + "api_version": "core/v2", + "metadata": { + "created_by": "admin", + "name": "add_org_sec_ops" + }, + "spec": { + "eval": "data = JSON.parse(JSON.stringify(event)); data['organization'] = 'sec_ops'; return JSON.stringify(data)", + "type": "javascript" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Combine existing attributes with JavaScript mutators + +Use a JavaScript mutator to create a new attribute from a combination of multiple existing attributes and add the new attribute to events. + +This example combines the event namespace and the name of the check that generated the event into a single new attribute, `origination`: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Mutator +api_version: core/v2 +metadata: + name: add_origination_attribute +spec: + eval: >- + data = JSON.parse(JSON.stringify(event)); data.origination = + data.metadata.namespace + data.check.metadata.name; return + JSON.stringify(data) + type: javascript +{{< /code >}} + +{{< code json >}} +{ + "type": "Mutator", + "api_version": "core/v2", + "metadata": { + "name": "add_origination_attribute" + }, + "spec": { + "eval": "data = JSON.parse(JSON.stringify(event)); data.origination = data.metadata.namespace + data.check.metadata.name; return JSON.stringify(data)", + "type": "javascript" + } +} +{{< /code >}} + +{{< /language-toggle >}} + + +[1]: ../../../plugins/assets/ +[2]: #metadata-attributes +[3]: ../../../operations/control-access/namespaces/ +[4]: ../../../plugins/use-assets-to-install-plugins/ +[5]: ../../../sensuctl/create-manage-resources/#create-resources +[6]: #spec-attributes +[7]: https://regex101.com/r/zo9mQU/2 +[8]: ../../../api/#response-filtering +[9]: ../../../sensuctl/filter-responses/ +[10]: ../../../operations/manage-secrets/secrets/ +[11]: ../../../operations/manage-secrets/secrets-providers/ +[12]: ../../observe-filter/filters/ +[13]: ../../../web-ui/search#search-for-labels +[14]: ../../../operations/manage-secrets/secrets-management/ +[15]: ../../../web-ui/search/ +[16]: ../ +[17]: ../../../observability-pipeline/ +[18]: #javascript-mutators +[19]: https://github.com/robertkrimen/otto +[20]: ../../observe-schedule/backend/#event-logging +[21]: #pipe-mutators +[22]: #eval-attribute +[23]: #add-new-event-attributes-with-javascript-mutators +[24]: #combine-existing-attributes-with-javascript-mutators +[25]: #env-vars-attribute +[26]: ../../../release-notes/#652-release-notes +[27]: ../../observe-process/pipelines/ diff --git a/content/sensu-go/6.12/operations/_index.md b/content/sensu-go/6.12/operations/_index.md new file mode 100644 index 0000000000..cb4ed12fd2 --- /dev/null +++ b/content/sensu-go/6.12/operations/_index.md @@ -0,0 +1,89 @@ +--- +title: "Operations" +description: "Read Sensu's Operations documentation to install, deploy, and operate Sensu, from local installation through a large-scale deployment with secrets management." +product: "Sensu Go" +version: "6.12" +weight: 20 +layout: "single" +toc: true +menu: + sensu-go-6.12: + identifier: operations +--- + +The Operations category will help you get Sensu up and running, from your first installation in your local development environment through a large-scale Sensu deployment using secrets management. +You'll also learn how to keep your Sensu implementation running, with guides for upgrading, monitoring, and troubleshooting. + +## Monitoring as code + +[Monitoring as code with Sensu][31] explains how to use Sensu’s end-to-end monitoring as code approach to manage your observability configuration the same way you build, test, and deploy your applications and infrastructure. + +## Deploy Sensu + +[Deploy Sensu][1] describes how to plan, install, configure, and deploy Sensu’s flexible monitoring and observability pipeline. + +To plan your Sensu deployment, read the [hardware requirements][6] and [deployment architecture][7] pages. +To start using Sensu locally or in development environments, follow the steps in the [Install Sensu][8] guide. + +When you're ready to deploy Sensu in production, learn to [generate certificates][9], [secure your Sensu installation][10], [run a Sensu cluster][11], and [reach multi-cluster visibility][12]. +You'll also find guides for scaling your implementation with Sensu's [Enterprise datastore][13] and using [configuration management tools][14] to ensure repeatable Sensu deployments and consistent configuration. + +## Control Access + +[Control Access][2] explains how Sensu administrators control access by authentication (verifying user identities) and authorization (establishing and managing user permissions for Sensu resources). + +Sensu requires username and password authentication to access the web UI, API, and sensuctl command line tool. +Use Sensu’s [built-in basic authentication][15] or configure external authentication providers via [Lightweight Directory Access Protocol (LDAP)][16], [Active Directory (AD)][17], or [OpenID Connect 1.0 protocol (OIDC)][18] to authenticate your Sensu users. + +Next, learn to configure authorization for your authenticated Sensu users with [role-based access control (RBAC)][19] and set up user permissions for interacting with Sensu resources. + +## Maintain Sensu + +[Maintain Sensu][3] includes upgrade, migration, troubleshooting, and license management information to keep your Sensu implementation running smoothly. + +Follow our step-by-step instructions to [upgrade to the latest version of Sensu][20] from any earlier version. +If you're still using Sensu Core or Sensu Enterprise, read [Migrate from Sensu Core and Sensu Enterprise to Sensu Go][21]. +You can also learn how to activate and and view your commercial [Sensu license][23] or [troubleshoot][22] to identify and resolve problems with your Sensu implementation, from reading and configuring Sensu service logs to using Sensu handlers and filters to test and debug your implementation. + +## Monitor Sensu + +[Monitor Sensu][4] covers how to [log Sensu services][24], [monitor your Sensu backend][25] with a secondary instance, and [retrieve and process health data][26] for your Sensu cluster. +You can also learn about [Tessen][27], the Sensu call-home service, which helps us understand how Sensu is being used and make informed decisions about product improvements. + +## Manage Secrets + +[Manage Secrets][5] explains how to [use Sensu’s secrets management][28] to eliminate the need to expose secrets like usernames, passwords, and access keys in your Sensu configuration. +Learn to configure [secrets][29] and [secrets providers][30] resources to obtain secrets from one or more external secrets providers, refer to external secrets, and consume secrets via backend environment variables. + + +[1]: deploy-sensu/ +[2]: control-access/ +[3]: maintain-sensu/ +[4]: monitor-sensu/ +[5]: manage-secrets/ +[6]: deploy-sensu/hardware-requirements/ +[7]: deploy-sensu/deployment-architecture/ +[8]: deploy-sensu/install-sensu/ +[9]: deploy-sensu/generate-certificates/ +[10]: deploy-sensu/secure-sensu/ +[11]: deploy-sensu/cluster-sensu/ +[12]: deploy-sensu/use-federation/ +[13]: deploy-sensu/scale-event-storage/ +[14]: deploy-sensu/configuration-management/ +[15]: control-access/#use-built-in-basic-authentication +[16]: control-access/ldap-auth/ +[17]: control-access/ad-auth/ +[18]: control-access/oidc-auth/ +[19]: control-access/create-read-only-user/ +[20]: maintain-sensu/upgrade/ +[21]: maintain-sensu/migrate/ +[22]: maintain-sensu/troubleshoot/ +[23]: maintain-sensu/license/ +[24]: monitor-sensu/log-sensu-systemd/ +[25]: monitor-sensu/monitor-sensu-with-sensu/ +[26]: monitor-sensu/health/ +[27]: monitor-sensu/tessen/ +[28]: manage-secrets/secrets-management/ +[29]: manage-secrets/secrets/ +[30]: manage-secrets/secrets-providers/ +[31]: monitoring-as-code/ diff --git a/content/sensu-go/6.12/operations/control-access/_index.md b/content/sensu-go/6.12/operations/control-access/_index.md new file mode 100644 index 0000000000..d273b651b7 --- /dev/null +++ b/content/sensu-go/6.12/operations/control-access/_index.md @@ -0,0 +1,96 @@ +--- +title: "Control Access" +description: "Set up access control for Sensu, the flexible observability pipeline. Read these documents to authenticate to Sensu and authorize access for Sensu users." +product: "Sensu Go" +version: "6.12" +weight: 20 +layout: "single" +toc: true +menu: + sensu-go-6.12: + parent: operations + identifier: control-access +--- + +Sensu administrators control access by authentication and authorization. + +Authentication verifies user identities to confirm that users are who they say they are. +Sensu requires username and password authentication to access the web UI, API, and sensuctl command line tool. +You can use Sensu's [built-in basic authentication][14] or configure [external authentication providers][15]. + +{{% notice note %}} +**NOTE**: For API-specific authentication, read the [API overview](../../api/#access-control) and [Use API keys to authenticate to Sensu](use-apikeys/). +{{% /notice %}} + +Authorization establishes and manages user permissions: the extent of access users have for different Sensu resources. +Configure authorization with [role-based access control (RBAC)][4] to exercise fine-grained control over how they interact with Sensu resources. + +## Authentication + +Sensu web UI and sensuctl command line tool users can authenticate via [built-in basic authentication][14] or Lightweight Directory Access Protocol (LDAP), Active Directory (AD), or OpenID Connect 1.0 protocol (OIDC) when the administrator configures [external single sign-on (SSO) authentication providers][15]. + +Sensu agents authenticate to the Sensu backend using either [basic][14] or [mutual transport layer security (TLS)][20] authentication. + +### Use built-in basic authentication + +Sensu's built-in basic authentication allows you to create and manage user credentials (usernames and passwords) with [core/v2/users API endpoints][53], either directly or using [sensuctl][2]. +The basic authentication provider does not depend on external services and is not configurable. + +Sensu hashes user passwords using the [bcrypt][26] algorithm and records the basic authentication credentials in [etcd][54]. + +### Use a single sign-on (SSO) authentication provider + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access authentication providers for single sign-on (SSO) in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../commercial/). +{{% /notice %}} + +In addition to built-in basic authentication, Sensu includes commercial support for single sign-on (SSO) authentication using external authentication providers via Lightweight Directory Access Protocol (LDAP), Active Directory (AD), or OpenID Connect 1.0 protocol (OIDC). + +Read [Configure single sign-on (SSO) authentication][6] for general information about configuring an SSO authentication provider. +Read the [LDAP][44], [AD][37], or [OIDC][7] reference documentation for provider-specific information. + +## Authorization + +After you set up authentication, configure authorization via [role-based access control (RBAC)][4] to give those users permissions within Sensu. +RBAC allows you to specify actions users are allowed to take against resources, within namespaces or across all namespaces, based on roles bound to the user or to one or more groups the user is a member of. +Read [Create a read-only user][5] for an example. + +- **Namespaces** partition resources within Sensu. +Sensu entities, checks, handlers, and other [namespaced resources][17] belong to a single namespace. +- **Roles** create sets of permissions (like GET and DELETE) tied to resource types. +**Cluster roles** apply permissions across all namespaces and may include access to [cluster-wide resources][18] like users and namespaces. +- **Role bindings** assign a role to a set of users and groups within a namespace. +**Cluster role bindings** assign a cluster role to a set of users and groups across all namespaces. + +To enable permissions for external users and groups within Sensu, you can create a set of [roles, cluster roles][11], [role bindings, and cluster role bindings][13] that map to the usernames and group names in your authentication provider. + +After you configure an authentication provider and establish the roles and bindings to grant authenticated users the desired privileges, those users can log in via [sensuctl][36] and the [web UI][1] using a single-sign-on username and password. +Users do *not* need to provide the username prefix for the authentication provider when logging in to Sensu. + + +[1]: ../../web-ui/#sign-in-to-the-web-ui +[2]: ../../sensuctl/ +[3]: rbac#default-users +[4]: rbac/ +[5]: create-read-only-user/ +[6]: sso/ +[7]: oidc-auth/ +[8]: ../../api/ +[11]: rbac#roles-and-cluster-roles +[13]: rbac#role-bindings-and-cluster-role-bindings +[14]: #use-built-in-basic-authentication +[15]: #use-a-single-sign-on-sso-authentication-provider +[16]: rbac/#view-users +[17]: rbac#namespaced-resource-types +[18]: rbac#cluster-wide-resource-types +[19]: ../maintain-sensu/troubleshoot#log-levels +[20]: ../deploy-sensu/secure-sensu/#optional-configure-sensu-agent-mtls-authentication +[26]: https://en.wikipedia.org/wiki/Bcrypt +[36]: ../../sensuctl/#first-time-setup-and-authentication +[37]: ad-auth/ +[38]: ../../sensuctl/create-manage-resources/#create-resources +[40]: ldap-auth/#ldap-server-attributes +[44]: ldap-auth/ +[53]: ../../api/core/users/ +[54]: https://etcd.io/ diff --git a/content/sensu-go/6.12/operations/control-access/ad-auth.md b/content/sensu-go/6.12/operations/control-access/ad-auth.md new file mode 100644 index 0000000000..d0c8f536d4 --- /dev/null +++ b/content/sensu-go/6.12/operations/control-access/ad-auth.md @@ -0,0 +1,1003 @@ +--- +title: "Active Directory (AD) reference" +linkTitle: "AD Reference" +reference_title: "Active Directory (AD)" +type: "reference" +description: "Read this reference to configure single sign-on (SSO) authentication for Sensu using Microsoft Active Directory (AD)." +weight: 50 +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: control-access +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access active directory (AD) authentication for single sign-on (SSO) in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} + +Sensu requires username and password authentication to access the [web UI][1], [API][8], and [sensuctl][2] command line tool. + +In addition to the [built-in basic authentication][4], Sensu offers [commercial support][6] for using Microsoft Active Directory (AD) for single sign-on (SSO) authentication. +The AD authentication provider is based on the [LDAP authentication provider][44]. + +To use AD authentication for Azure, follow Microsoft's tutorial to [set up secure LDAP in your Azure account][10] and create the host and certificates you need. + +For general information about configuring authentication providers, read [Configure single sign-on (SSO) authentication][12]. + +## AD configuration examples + +**Example AD configuration: Minimum required attributes** + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: ad +api_version: authentication/v2 +metadata: + name: activedirectory +spec: + servers: + - group_search: + base_dn: dc=acme,dc=org + host: 127.0.0.1 + user_search: + base_dn: dc=acme,dc=org +{{< /code >}} + +{{< code json >}} +{ + "type": "ad", + "api_version": "authentication/v2", + "spec": { + "servers": [ + { + "host": "127.0.0.1", + "group_search": { + "base_dn": "dc=acme,dc=org" + }, + "user_search": { + "base_dn": "dc=acme,dc=org" + } + } + ] + }, + "metadata": { + "name": "activedirectory" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +**Example AD configuration: All attributes** + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: ad +api_version: authentication/v2 +metadata: + name: activedirectory +spec: + allowed_groups: [] + groups_prefix: ad + servers: + - binding: + password: YOUR_PASSWORD + user_dn: cn=binder,cn=users,dc=acme,dc=org + client_cert_file: /path/to/ssl/cert.pem + client_key_file: /path/to/ssl/key.pem + default_upn_domain: example.org + include_nested_groups: true + group_search: + attribute: member + base_dn: dc=acme,dc=org + name_attribute: cn + object_class: group + host: 127.0.0.1 + insecure: false + port: 636 + security: tls + trusted_ca_file: /path/to/trusted-certificate-authorities.pem + user_search: + attribute: sAMAccountName + base_dn: dc=acme,dc=org + name_attribute: displayName + object_class: person + username_prefix: ad +{{< /code >}} + +{{< code json >}} +{ + "type": "ad", + "api_version": "authentication/v2", + "spec": { + "servers": [ + { + "host": "127.0.0.1", + "port": 636, + "insecure": false, + "security": "tls", + "trusted_ca_file": "/path/to/trusted-certificate-authorities.pem", + "client_cert_file": "/path/to/ssl/cert.pem", + "client_key_file": "/path/to/ssl/key.pem", + "default_upn_domain": "example.org", + "include_nested_groups": true, + "binding": { + "user_dn": "cn=binder,cn=users,dc=acme,dc=org", + "password": "YOUR_PASSWORD" + }, + "group_search": { + "base_dn": "dc=acme,dc=org", + "attribute": "member", + "name_attribute": "cn", + "object_class": "group" + }, + "user_search": { + "base_dn": "dc=acme,dc=org", + "attribute": "sAMAccountName", + "name_attribute": "displayName", + "object_class": "person" + } + } + ], + "allowed_groups": [], + "groups_prefix": "ad", + "username_prefix": "ad" + }, + "metadata": { + "name": "activedirectory" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +{{% notice note %}} +**NOTE**: If you specify allowed groups, the group names must exactly match the names the authentication provider returns to the Sensu backend. +{{% /notice %}} + +**Example AD configuration: Use `memberOf` attribute instead of `group_search`** + +AD automatically returns a `memberOf` attribute in users' accounts. +The `memberOf` attribute contains the user's group membership, which effectively removes the requirement to look up the user's groups. + +To use the `memberOf` attribute in your AD implementation, remove the `group_search` object from your AD config: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: ad +api_version: authentication/v2 +metadata: + name: activedirectory +spec: + servers: + host: 127.0.0.1 + user_search: + base_dn: dc=acme,dc=org +{{< /code >}} + +{{< code json >}} +{ + "type": "ad", + "api_version": "authentication/v2", + "spec": { + "servers": [ + { + "host": "127.0.0.1", + "user_search": { + "base_dn": "dc=acme,dc=org" + } + } + ] + }, + "metadata": { + "name": "activedirectory" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +After you configure AD to use the `memberOf` attribute, the `debug` log level will include the following log entries: + +{{< code text >}} +{"component":"authentication/v2","level":"debug","msg":"using the \"memberOf\" attribute to determine the group membership of user \"user1\"","time":"2020-06-25T14:10:58-04:00"} +{"component":"authentication/v2","level":"debug","msg":"found 1 LDAP group(s): [\"sensu\"]","time":"2020-06-25T14:10:58-04:00"} +{{< /code >}} + +## AD specification + +### AD top-level attributes + +type | +-------------|------ +description | Top-level attribute that specifies the [`sensuctl create`][38] resource type. For AD definitions, the `type` should always be `ad`. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +type: ad +{{< /code >}} +{{< code json >}} +{ + "type": "ad" +} +{{< /code >}} +{{< /language-toggle >}} + +api_version | +-------------|------ +description | Top-level attribute that specifies the Sensu API group and version. For AD definitions, the `api_version` should always be `authentication/v2`. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +api_version: authentication/v2 +{{< /code >}} +{{< code json >}} +{ + "api_version": "authentication/v2" +} +{{< /code >}} +{{< /language-toggle >}} + +metadata | +-------------|------ +description | Top-level map that contains the AD definition `name`. Review the [metadata attributes][23] for details. +required | true +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +metadata: + name: activedirectory +{{< /code >}} +{{< code json >}} +{ + "metadata": { + "name": "activedirectory" + } +} +{{< /code >}} +{{< /language-toggle >}} + +spec | +-------------|------ +description | Top-level map that includes the AD [spec attributes][45]. +required | true +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +spec: + servers: + - host: 127.0.0.1 + port: 636 + insecure: false + security: tls + trusted_ca_file: "/path/to/trusted-certificate-authorities.pem" + client_cert_file: "/path/to/ssl/cert.pem" + client_key_file: "/path/to/ssl/key.pem" + default_upn_domain: example.org + include_nested_groups: true + binding: + user_dn: cn=binder,cn=users,dc=acme,dc=org + password: YOUR_PASSWORD + group_search: + base_dn: dc=acme,dc=org + attribute: member + name_attribute: cn + object_class: group + user_search: + base_dn: dc=acme,dc=org + attribute: sAMAccountName + name_attribute: displayName + object_class: person + allowed_groups: [] + groups_prefix: ad + username_prefix: ad +{{< /code >}} +{{< code json >}} +{ + "spec": { + "servers": [ + { + "host": "127.0.0.1", + "port": 636, + "insecure": false, + "security": "tls", + "trusted_ca_file": "/path/to/trusted-certificate-authorities.pem", + "client_cert_file": "/path/to/ssl/cert.pem", + "client_key_file": "/path/to/ssl/key.pem", + "default_upn_domain": "example.org", + "include_nested_groups": true, + "binding": { + "user_dn": "cn=binder,cn=users,dc=acme,dc=org", + "password": "YOUR_PASSWORD" + }, + "group_search": { + "base_dn": "dc=acme,dc=org", + "attribute": "member", + "name_attribute": "cn", + "object_class": "group" + }, + "user_search": { + "base_dn": "dc=acme,dc=org", + "attribute": "sAMAccountName", + "name_attribute": "displayName", + "object_class": "person" + } + } + ], + "allowed_groups": [], + "groups_prefix": "ad", + "username_prefix": "ad" + } +} +{{< /code >}} +{{< /language-toggle >}} + +### AD metadata attributes + +| name | | +-------------|------ +description | A unique string used to identify the AD configuration. Names cannot contain special characters or spaces (validated with Go regex [`\A[\w\.\-]+\z`][42]). +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +name: activedirectory +{{< /code >}} +{{< code json >}} +{ + "name": "activedirectory" +} +{{< /code >}} +{{< /language-toggle >}} + +### AD spec attributes + +| servers | | +-------------|------ +description | The list of [AD servers][46] to use. During the authentication process, Sensu attempts to authenticate against each AD server in sequence until authentication is successful or there are no more servers to try. +required | true +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +servers: +- host: 127.0.0.1 + port: 636 + insecure: false + security: tls + trusted_ca_file: "/path/to/trusted-certificate-authorities.pem" + client_cert_file: "/path/to/ssl/cert.pem" + client_key_file: "/path/to/ssl/key.pem" + default_upn_domain: example.org + include_nested_groups: true + binding: + user_dn: cn=binder,cn=users,dc=acme,dc=org + password: YOUR_PASSWORD + group_search: + base_dn: dc=acme,dc=org + attribute: member + name_attribute: cn + object_class: group + user_search: + base_dn: dc=acme,dc=org + attribute: sAMAccountName + name_attribute: displayName + object_class: person +{{< /code >}} +{{< code json >}} +{ + "servers": [ + { + "host": "127.0.0.1", + "port": 636, + "insecure": false, + "security": "tls", + "trusted_ca_file": "/path/to/trusted-certificate-authorities.pem", + "client_cert_file": "/path/to/ssl/cert.pem", + "client_key_file": "/path/to/ssl/key.pem", + "default_upn_domain": "example.org", + "include_nested_groups": true, + "binding": { + "user_dn": "cn=binder,cn=users,dc=acme,dc=org", + "password": "YOUR_PASSWORD" + }, + "group_search": { + "base_dn": "dc=acme,dc=org", + "attribute": "member", + "name_attribute": "cn", + "object_class": "group" + }, + "user_search": { + "base_dn": "dc=acme,dc=org", + "attribute": "sAMAccountName", + "name_attribute": "displayName", + "object_class": "person" + } + } + ] +} +{{< /code >}} +{{< /language-toggle >}} + + + +| allowed_groups | | +-------------|------ +description | An array of allowed AD group strings to include in the tokenized identity claim. Use to specify which groups to encode in the authentication provider's JSON Web Token (JWT) when the authenticated AD user is a member of many groups and the tokenized identity claim would be too large for correct web client operation.{{% notice note %}}**NOTE**: Allowed group names are case-sensitive and must exactly match the group names the authentication provider returns to the Sensu backend. +{{% /notice %}} +required | false +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +allowed_groups: +- Sensu_Viewers +- Sensu_Operators +{{< /code >}} +{{< code json >}} +{ + "allowed_groups": [ + "Sensu_Viewers", + "Sensu_Operators" + ] +} +{{< /code >}} +{{< /language-toggle >}} + + + +| groups_prefix | | +-------------|------ +description | The prefix added to all AD groups. Sensu appends the groups_prefix with a colon. For example, for the groups_prefix `ad` and the group `dev`, the resulting group name in Sensu is `ad:dev`. Use the groups_prefix when integrating AD groups with Sensu RBAC [role bindings and cluster role bindings][13]. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +groups_prefix: ad +{{< /code >}} +{{< code json >}} +{ + "groups_prefix": "ad" +} +{{< /code >}} +{{< /language-toggle >}} + + + +| username_prefix | | +-------------|------ +description | The prefix added to all AD usernames. Sensu appends the username_prefix with a colon. For example, for the username_prefix `ad` and the user `alice`, the resulting username in Sensu is `ad:alice`. Use the username_prefix when integrating AD users with Sensu RBAC [role bindings and cluster role bindings][13]. Users _do not_ need to provide the username_prefix when logging in to Sensu. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +username_prefix: ad +{{< /code >}} +{{< code json >}} +{ + "username_prefix": "ad" +} +{{< /code >}} +{{< /language-toggle >}} + +### AD server attributes + +| host | | +-------------|------ +description | AD server IP address or [fully qualified domain name (FQDN)][41]. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +host: 127.0.0.1 +{{< /code >}} +{{< code json >}} +{ + "host": "127.0.0.1" +} +{{< /code >}} +{{< /language-toggle >}} + +| port | | +-------------|------ +description | AD server port. +required | true +type | Integer +default | `389` for insecure connections; `636` for TLS connections +example | {{< language-toggle >}} +{{< code yml >}} +port: 636 +{{< /code >}} +{{< code json >}} +{ + "port": 636 +} +{{< /code >}} +{{< /language-toggle >}} + + + +| insecure | | +-------------|------ +description | Skips SSL certificate verification when set to `true`. {{% notice warning %}} +**WARNING**: Do not use an insecure connection in production environments. +{{% /notice %}} +required | false +type | Boolean +default | `false` +example | {{< language-toggle >}} +{{< code yml >}} +insecure: false +{{< /code >}} +{{< code json >}} +{ + "insecure": false +} +{{< /code >}} +{{< /language-toggle >}} + + + +| security | | +-------------|------ +description | Determines the encryption type to be used for the connection to the AD server: `insecure` (unencrypted connection; not recommended for production), `tls` (secure encrypted connection), or `starttls` (unencrypted connection upgrades to a secure connection). +type | String +default | `tls` +example | {{< language-toggle >}} +{{< code yml >}} +security: tls +{{< /code >}} +{{< code json >}} +{ + "security": "tls" +} +{{< /code >}} +{{< /language-toggle >}} + +| trusted_ca_file | | +-------------|------ +description | Path to an alternative CA bundle file in PEM format to be used instead of the system's default bundle. This CA bundle is used to verify the server's certificate. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +trusted_ca_file: /path/to/trusted-certificate-authorities.pem +{{< /code >}} +{{< code json >}} +{ + "trusted_ca_file": "/path/to/trusted-certificate-authorities.pem" +} +{{< /code >}} +{{< /language-toggle >}} + +| client_cert_file | | +-------------|------ +description | Path to the certificate that should be sent to the server if requested. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +client_cert_file: /path/to/ssl/cert.pem +{{< /code >}} +{{< code json >}} +{ + "client_cert_file": "/path/to/ssl/cert.pem" +} +{{< /code >}} +{{< /language-toggle >}} + +| client_key_file | | +-------------|------ +description | Path to the key file associated with the `client_cert_file`. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +client_key_file: /path/to/ssl/key.pem +{{< /code >}} +{{< code json >}} +{ + "client_key_file": "/path/to/ssl/key.pem" +} +{{< /code >}} +{{< /language-toggle >}} + + + +| binding | | +-------------|------ +description | The AD account that performs user and group lookups. If your server supports anonymous binding, you can omit the `user_dn` or `password` attributes to query the directory without credentials. To use anonymous binding with AD, the `ANONYMOUS LOGON` object requires read permissions for users and groups. Review the [binding attributes][43] for details. +required | false +type | Map +example | {{< language-toggle >}} +{{< code yml >}} +binding: + user_dn: cn=binder,cn=users,dc=acme,dc=org + password: YOUR_PASSWORD +{{< /code >}} +{{< code json >}} +{ + "binding": { + "user_dn": "cn=binder,cn=users,dc=acme,dc=org", + "password": "YOUR_PASSWORD" + } +} +{{< /code >}} +{{< /language-toggle >}} + +| group_search | | +-------------|------ +description | Search configuration for groups. Review the [group search attributes][47] for more information. Remove the `group_search` object from your configuration to use the `memberOf` attribute instead. +required | false +type | Map +example | {{< language-toggle >}} +{{< code yml >}} +group_search: + base_dn: dc=acme,dc=org + attribute: member + name_attribute: cn + object_class: group +{{< /code >}} +{{< code json >}} +{ + "group_search": { + "base_dn": "dc=acme,dc=org", + "attribute": "member", + "name_attribute": "cn", + "object_class": "group" + } +} +{{< /code >}} +{{< /language-toggle >}} + + + +| user_search | | +-------------|------ +description | Search configuration for users. Review the [user search attributes][48] for more information. +required | true +type | Map +example | {{< language-toggle >}} +{{< code yml >}} +user_search: + base_dn: dc=acme,dc=org + attribute: sAMAccountName + name_attribute: displayName + object_class: person +{{< /code >}} +{{< code json >}} +{ + "user_search": { + "base_dn": "dc=acme,dc=org", + "attribute": "sAMAccountName", + "name_attribute": "displayName", + "object_class": "person" + } +} +{{< /code >}} +{{< /language-toggle >}} + +| default_upn_domain | | +-------------|------ +description | Enables UPN authentication when set. The default UPN suffix that will be appended to the username when a domain is not specified during login (for example, `user` becomes `user@defaultdomain.xyz`). {{% notice warning %}} +**WARNING**: When using UPN authentication, users must re-authenticate to apply any changes to group membership on the AD server since their last authentication. For example, if you remove a user from a group with administrator permissions for the current session (such as a terminated employee), Sensu will not apply the change until the user logs out and tries to start a new session. Likewise, under UPN, users cannot be forced to log out of Sensu. To apply group membership updates without re-authentication, specify a binding account or enable anonymous binding. +{{% /notice %}} +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +default_upn_domain: example.org +{{< /code >}} +{{< code json >}} +{ + "default_upn_domain": "example.org" +} +{{< /code >}} +{{< /language-toggle >}} + +| include_nested_groups | | +-------------|------ +description | If `true`, the group search includes any nested groups a user is a member of. If `false`, the group search includes only the top-level groups a user is a member of. +required | false +type | Boolean +example | {{< language-toggle >}} +{{< code yml >}} +include_nested_groups: true +{{< /code >}} +{{< code json >}} +{ + "include_nested_groups": true +} +{{< /code >}} +{{< /language-toggle >}} + +### AD binding attributes + +| user_dn | | +-------------|------ +description | The AD account that performs user and group lookups. We recommend using a read-only account. Use the distinguished name (DN) format, such as `cn=binder,cn=users,dc=domain,dc=tld`. If your server supports anonymous binding, you can omit this attribute to query the directory without credentials. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +user_dn: cn=binder,cn=users,dc=acme,dc=org +{{< /code >}} +{{< code json >}} +{ + "user_dn": "cn=binder,cn=users,dc=acme,dc=org" +} +{{< /code >}} +{{< /language-toggle >}} + +| password | | +-------------|------ +description | Password for the `user_dn` account. If your server supports anonymous binding, you can omit this attribute to query the directory without credentials. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +password: YOUR_PASSWORD +{{< /code >}} +{{< code json >}} +{ + "password": "YOUR_PASSWORD" +} +{{< /code >}} +{{< /language-toggle >}} + +### AD group search attributes + +| base_dn | | +-------------|------ +description | Tells Sensu which part of the directory tree to search. For example, `dc=acme,dc=org` searches within the `acme.org` directory. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +base_dn: dc=acme,dc=org +{{< /code >}} +{{< code json >}} +{ + "base_dn": "dc=acme,dc=org" +} +{{< /code >}} +{{< /language-toggle >}} + +| attribute | | +-------------|------ +description | Used for comparing result entries. Combined with other filters as
    `"(=)"`. +required | false +type | String +default | `member` +example | {{< language-toggle >}} +{{< code yml >}} +attribute: member +{{< /code >}} +{{< code json >}} +{ + "attribute": "member" +} +{{< /code >}} +{{< /language-toggle >}} + + + +| name_attribute | | +-------------|------ +description | Represents the attribute to use as the entry name. +required | false +type | String +default | `cn` +example | {{< language-toggle >}} +{{< code yml >}} +name_attribute: cn +{{< /code >}} +{{< code json >}} +{ + "name_attribute": "cn" +} +{{< /code >}} +{{< /language-toggle >}} + +| object_class | | +-------------|------ +description | Identifies the class of objects returned in the search result. Combined with other filters as `"(objectClass=)"`. +required | false +type | String +default | `group` +example | {{< language-toggle >}} +{{< code yml >}} +object_class: group +{{< /code >}} +{{< code json >}} +{ + "object_class": "group" +} +{{< /code >}} +{{< /language-toggle >}} + +### AD user search attributes + +| base_dn | | +-------------|------ +description | Tells Sensu which part of the directory tree to search. For example, `dc=acme,dc=org` searches within the `acme.org` directory. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +base_dn: dc=acme,dc=org +{{< /code >}} +{{< code json >}} +{ + "base_dn": "dc=acme,dc=org" +} +{{< /code >}} +{{< /language-toggle >}} + +| attribute | | +-------------|------ +description | Used for comparing result entries. Combined with other filters as
    `"(=)"`. +required | false +type | String +default | `sAMAccountName` +example | {{< language-toggle >}} +{{< code yml >}} +attribute: sAMAccountName +{{< /code >}} +{{< code json >}} +{ + "attribute": "sAMAccountName" +} +{{< /code >}} +{{< /language-toggle >}} + +| name_attribute | | +-------------|------ +description | Represents the attribute to use as the entry name. +required | false +type | String +default | `displayName` +example | {{< language-toggle >}} +{{< code yml >}} +name_attribute: displayName +{{< /code >}} +{{< code json >}} +{ + "name_attribute": "displayName" +} +{{< /code >}} +{{< /language-toggle >}} + +| object_class | | +-------------|------ +description | Identifies the class of objects returned in the search result. Combined with other filters as `"(objectClass=)"`. +required | false +type | String +default | `person` +example | {{< language-toggle >}} +{{< code yml >}} +object_class: person +{{< /code >}} +{{< code json >}} +{ + "object_class": "person" +} +{{< /code >}} +{{< /language-toggle >}} + +## AD troubleshooting + +To troubleshoot any issue with AD authentication, start by [increasing the log verbosity][3] of sensu-backend to the [debug log level][5]. +Most authentication and authorization errors are only displayed on the debug log level to avoid flooding the log files. + +{{% notice note %}} +**NOTE**: If you can't locate any log entries referencing AD authentication, run [sensuctl auth list](../sso/#manage-authentication-providers) to make sure that you successfully installed the AD provider. +{{% /notice %}} + +### Authentication + +This section lists common authentication error messages and describes possible solutions for each of them. + +#### `failed to connect: AD Result Code 200 "Network Error"` + +The AD provider couldn't establish a TCP connection to the AD server. +Verify the `host` and `port` attributes. +If you are not using AD over TLS/SSL, make sure to set the value of the [`security` attribute][11] to `insecure` for plaintext communication. + +#### `certificate signed by unknown authority` + +If you are using a self-signed certificate, make sure to set the [`insecure` attribute][18] to `true`. +This will bypass verification of the certificate's signing authority. + +#### `failed to bind: ...` + +The first step for authenticating a user with the AD provider is to bind to the AD server using the service account specified in the [`binding` object][14]. +Make sure the [`user_dn` attribute][43] specifies a valid **DN** and that its password is correct. + +#### `user was not found` + +The user search failed. +No user account could be found with the given username. +Check the [`user_search` object][15] and make sure that: + +- The specified `base_dn` contains the requested user entry DN +- The specified `attribute` contains the _username_ as its value in the user entry +- The `object_class` attribute corresponds to the user entry object class + +#### `ad search for user returned x results, expected only 1` + +The user search returned more than one user entry, so the provider could not determine which of these entries to use. +Change the [`user_search` object][15] so the provided `username` can be used to uniquely identify a user entry. +Here are two methods to try: + +- Adjust the `attribute` so its value (which corresponds to the `username`) is unique among the user entries +- Adjust the `base_dn` so it only includes one of the user entries + +#### `ad entry missing required attribute ` + +The user entry returned (identified by ``) doesn't include the attribute specified by [`name_attribute` object][9], so the AD provider could not determine which attribute to use as the username in the user entry. +Adjust the `name_attribute` so it specifies a human-readable name for the user. + +#### `ad group entry missing and cn attributes` + +The group search returned a group entry (identified by ``) that doesn't have the [`name_attribute` object][9] or a `cn` attribute, so the AD provider could not determine which attribute to use as the group name in the group entry. +Adjust the `name_attribute` so it specifies a human-readable name for the group. + +### Authorization + +Once authenticated, each user needs to be granted permissions via either a `ClusterRoleBinding` or a `RoleBinding`. + +The way AD users and AD groups can be referred as subjects of a cluster role or role binding depends on the [`groups_prefix`][16] and [`username_prefix`][17] configuration attributes values of the AD provider. +For example, for the groups_prefix `ad` and the group `dev`, the resulting group name in Sensu is `ad:dev`. + +#### Permissions are not granted via the AD group(s) + +During authentication, the AD provider will print all groups found in AD (for example, `found 1 group(s): [dev]`) in the logs. +Keep in mind that this group name does not contain the [`groups_prefix`][16] at this point. + +The Sensu backend logs each attempt made to authorize an RBAC request. +This is useful for determining why a specific binding didn't grant the request. +For example: + +{{< code text >}} +[...] the user is not a subject of the ClusterRoleBinding cluster-admin [...] +[...] could not authorize the request with the ClusterRoleBinding system:user [...] +[...] could not authorize the request with any ClusterRoleBindings [...] +{{< /code >}} + + +[1]: ../../../web-ui/ +[2]: ../../../sensuctl/ +[3]: ../../maintain-sensu/troubleshoot/#increment-log-level-verbosity +[4]: ../#use-built-in-basic-authentication +[5]: ../../maintain-sensu/troubleshoot/#log-levels +[6]: ../../../commercial/ +[8]: ../../../api/ +[9]: #name-attribute-attribute +[10]: https://docs.microsoft.com/en-us/azure/active-directory-domain-services/tutorial-configure-ldaps +[11]: #security-attribute +[12]: ../sso/ +[13]: ../rbac#role-bindings-and-cluster-role-bindings +[14]: #binding-object +[15]: #user-search-object +[16]: #ad-groups-prefix +[17]: #ad-username-prefix +[18]: #insecure-attribute +[23]: #ad-metadata-attributes +[38]: ../../../sensuctl/create-manage-resources/#create-resources +[41]: https://en.wikipedia.org/wiki/Fully_qualified_domain_name +[42]: https://regex101.com/r/zo9mQU/2 +[43]: #ad-binding-attributes +[44]: ../ldap-auth/ +[45]: #ad-spec-attributes +[46]: #ad-server-attributes +[47]: #ad-group-search-attributes +[48]: #ad-user-search-attributes diff --git a/content/sensu-go/6.12/operations/control-access/apikeys.md b/content/sensu-go/6.12/operations/control-access/apikeys.md new file mode 100644 index 0000000000..e11bfcf44c --- /dev/null +++ b/content/sensu-go/6.12/operations/control-access/apikeys.md @@ -0,0 +1,220 @@ +--- +title: "API keys reference" +linkTitle: "API Keys Reference" +reference_title: "API keys" +type: "reference" +description: "Provide API keys, long-lived authentication tokens generated by the Sensu backend, to applications that want to interact with the Sensu API." +weight: 70 +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: control-access +--- + +API keys are long-lived authentication tokens that make it more convenient for Sensu plugins and other Sensu-adjacent applications to authenticate with the Sensu API. +Unlike [authentication tokens][2], API keys are persistent and do not need to be refreshed every 15 minutes. + +The Sensu backend generates API keys, and you can provide them to applications that want to interact with the Sensu API. + +Use the [core/v2/apikeys API endpoints][1] to create, retrieve, and delete API keys. + +## API key example + +This example shows an `APIKey` resource definition: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: APIKey +api_version: core/v2 +metadata: + name: 19803eb8-36a6-4203-a225-28ec4e9f4444 +spec: + created_at: 1570732266 + username: admin +{{< /code >}} + +{{< code json >}} +{ + "type": "APIKey", + "api_version": "core/v2", + "metadata" : { + "name": "19803eb8-36a6-4203-a225-28ec4e9f4444" + }, + "spec": { + "created_at": 1570732266, + "username": "admin" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Authorization header format + +Use the following header format to authenticate with API keys, replacing `` with your API key: + +{{< code curl >}} +Authorization: Key +{{< /code >}} + +This is different from the authentication token, which uses the `Authorization: Bearer` header format. + +When you specify an API key in a request, the system resolves it to an authentication token and continues through the regular authentication process. + +{{% notice note %}} +**NOTE**: The API key resource is not compatible with [`sensuctl create`](../../../sensuctl/create-manage-resources/#create-resources). +{{% /notice %}} + +## API key specification + +### Top-level attributes + +api_version | +-------------|------ +description | Top-level attribute that specifies the Sensu API group and version. The `api_version` should always be `core/v2`. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +api_version: core/v2 +{{< /code >}} +{{< code json >}} +{ + "api_version": "core/v2" +} +{{< /code >}} +{{< /language-toggle >}} + +metadata | +-------------|------ +description | Top-level collection of metadata about the API key, including `name` and `created_by`. The `metadata` map is always at the top level of the API key definition. This means that in `wrapped-json` and `yaml` formats, the `metadata` scope occurs outside the `spec` scope. +required | true +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +metadata: + name: 19803eb8-36a6-4203-a225-28ec4e9f4444 + created_by: admin +{{< /code >}} +{{< code json >}} +{ + "metadata": { + "name": "19803eb8-36a6-4203-a225-28ec4e9f4444", + "created_by": "admin" + } +} +{{< /code >}} +{{< /language-toggle >}} + +spec | +-------------|------ +description | Top-level map that includes the API key's [spec attributes][4]. +required | true +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +spec: + created_at: 1570732266 + username: admin +{{< /code >}} +{{< code json >}} +{ + "spec": { + "created_at": 1570732266, + "username": "admin" + } +} +{{< /code >}} +{{< /language-toggle >}} + +type | +-------------|------ +description | Top-level attribute that specifies the resource type. API keys should always be type `APIKey`. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +type: APIKey +{{< /code >}} +{{< code json >}} +{ + "type": "APIKey" +} +{{< /code >}} +{{< /language-toggle >}} + +### Metadata attributes + +| created_by | | +-------------|------ +description | Username of the Sensu user who created the API key or last updated the API key. Sensu automatically populates the `created_by` field when the API key is created or updated. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +created_by: admin +{{< /code >}} +{{< code json >}} +{ + "created_by": "admin" +} +{{< /code >}} +{{< /language-toggle >}} + +| name | | +-------------|------ +description | Unique string used to identify the API key. Sensu randomly generates a universally unique identifier (UUID) for the `name` value — users cannot provide a name for an API key. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +name: 19803eb8-36a6-4203-a225-28ec4e9f4444 +{{< /code >}} +{{< code json >}} +{ + "name": "19803eb8-36a6-4203-a225-28ec4e9f4444" +} +{{< /code >}} +{{< /language-toggle >}} + +### Spec attributes + +| created_at | | +-------------|------ +description | Time at which the API key was created. Unix timestamp that is automatically generated when the API key is created. +required | true +type | Integer +example | {{< language-toggle >}} +{{< code yml >}} +created_at: 1234567890 +{{< /code >}} +{{< code json >}} +{ + "created_at": 1234567890 +} +{{< /code >}} +{{< /language-toggle >}} + +| username | | +-------------|------ +description | User associated with the API key. +required | true +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +username: admin +{{< /code >}} +{{< code json >}} +{ + "username": "admin" +} +{{< /code >}} +{{< /language-toggle >}} + + +[1]: ../../../api/core/apikeys/ +[2]: ../../../api/other/auth/ +[4]: #spec-attributes diff --git a/content/sensu-go/6.12/operations/control-access/create-limited-service-accounts.md b/content/sensu-go/6.12/operations/control-access/create-limited-service-accounts.md new file mode 100644 index 0000000000..36ac4b322c --- /dev/null +++ b/content/sensu-go/6.12/operations/control-access/create-limited-service-accounts.md @@ -0,0 +1,327 @@ +--- +title: "Create limited service accounts" +linkTitle: "Create Limited Service Accounts" +guide_title: "Create limited service accounts" +type: "guide" +description: "Use Sensu's role-based access control (RBAC) to create limited service accounts so that applications can access and interact with Sensu resources." +weight: 40 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: control-access +--- + +In some cases, you may want to allow an application or service to interact with Sensu resources. +Use Sensu's [role-based access control (RBAC)][1] to create and configure accounts that represent applications or services rather than individual human users. +These limited service accounts give you fine-grained control of the access and permissions the application or service needs. + +For example, you might develop a service that displays a high-level view of your webserver statuses based on an aggregate check. +The service itself only needs an API key and permission to read the results of checks executed on your webservers so it can route the check results to the status display. +No human user needs to log into the service, and the service does not need edit or delete permissions. +A limited service account can provide only the necessary access and permissions. + +Limited service accounts are also useful for performing automated processes. +This guide explains how to create a limited service account to use with the [sensu/sensu-ec2-handler][13] dynamic runtime asset to automatically remove AWS EC2 instances that are not in a pending or running state. + +By default, Sensu includes a `default` namespace and an `admin` user with full permissions to create, modify, and delete resources within Sensu, including the RBAC resources required to configure a limited service account. + +## Requirements + +This guide requires a running Sensu [backend][3] and a [sensuctl][11] instance configured to connect to the backend as the [`admin` user][2]. + +## Create a limited service account + +Follow the steps in this section to create a limited service account, which requires: + +- A [user][7]. +- A [role][4] with get, list, and delete permissions for resources within the `default` [namespace][9]. +- A [role binding][5] that ties the role to the user. +- An [API key][12] for the user. + +{{% notice note %}} +**NOTE**: To use a service account to manage Sensu resources in more than one namespace, create a [cluster role](../rbac/#cluster-roles) instead of a role and a [cluster role binding](../rbac/#cluster-role-bindings) instead of a role binding. +{{% /notice %}} + +1. Create a user with the username `ec2-service` and a dynamically created random password: + + {{< code shell >}} +sensuctl user create ec2-service --password=$(head -c1M /dev/urandom | sha512sum | cut -d' ' -f1 | head -c 32) +{{< /code >}} + + This command creates the following user definition: + + {{< language-toggle >}} +{{< code text "YML" >}} +--- +type: User +api_version: core/v2 +metadata: + name: ec2-service +spec: + disabled: false + username: ec2-service +{{< /code >}} +{{< code text "JSON" >}} +{ + "type": "User", + "api_version": "core/v2", + "metadata": { + "name": "ec2-service" + }, + "spec": { + "disabled": false, + "username": "ec2-service" + } +} +{{< /code >}} +{{< /language-toggle >}} + +2. Create a `ec2-delete` role with get, list, and delete permissions for entity resources within the `default` namespace: + + {{< code shell >}} +sensuctl role create ec2-delete --verb get,list,delete --resource entities --namespace default +{{< /code >}} + + This command creates the role that has the permissions your service account will need: + + {{< language-toggle >}} +{{< code text "YML" >}} +--- +type: Role +api_version: core/v2 +metadata: + name: ec2-delete +spec: + rules: + - resource_names: null + resources: + - entities + verbs: + - get + - list + - delete +{{< /code >}} +{{< code text "JSON" >}} +{ + "type": "Role", + "api_version": "core/v2", + "metadata": { + "name": "ec2-delete" + }, + "spec": { + "rules": [ + { + "resource_names": null, + "resources": [ + "entities" + ], + "verbs": [ + "get", + "list", + "delete" + ] + } + ] + } +} +{{< /code >}} +{{< /language-toggle >}} + +3. Create an `ec2-service-delete` role binding to assign the `ec2-delete` role to the `ec2-service` user: + + {{< code shell >}} +sensuctl role-binding create ec2-service-delete --role ec2-delete --user ec2-service +{{< /code >}} + + This command creates the role binding that ties the correct permissions (via the `ec2-delete` role) with your service account (via the user `ec2-service`): + {{< language-toggle >}} +{{< code text "YML" >}} +--- +type: RoleBinding +api_version: core/v2 +metadata: + name: ec2-service-delete +spec: + role_ref: + name: ec2-delete + type: Role + subjects: + - name: ec2-service + type: User +{{< /code >}} +{{< code text "JSON" >}} +{ + "type": "RoleBinding", + "api_version": "core/v2", + "metadata": { + "name": "ec2-service-delete" + }, + "spec": { + "role_ref": { + "name": "ec2-delete", + "type": "Role" + }, + "subjects": [ + { + "name": "ec2-service", + "type": "User" + } + ] + } +} +{{< /code >}} +{{< /language-toggle >}} + +4. Create an API key for the `ec2-service` user: + + {{< code shell >}} +sensuctl api-key grant ec2-service +{{< /code >}} + + The response will include an API key that is assigned to the `ec2-service` user, which you will need to configure the EC2 handler. + +The `ec2-service` limited service account is now ready to use with the [sensu/sensu-ec2-handler][13] dynamic runtime asset. + +## Add the sensu/sensu-ec2-handler dynamic runtime asset + +To power the handler to remove AWS EC2 instances, use sensuctl to add the [sensu/sensu-ec2-handler][13] dynamic runtime asset: + +{{< code shell >}} +sensuctl asset add sensu/sensu-ec2-handler:0.4.0 +{{< /code >}} + +The response will indicate that the asset was added: + +{{< code text >}} +fetching bonsai asset: sensu/sensu-ec2-handler:0.4.0 +added asset: sensu/sensu-ec2-handler:0.4.0 + +You have successfully added the Sensu asset resource, but the asset will not get downloaded until +it's invoked by another Sensu resource (ex. check). To add this runtime asset to the appropriate +resource, populate the "runtime_assets" field with ["sensu/sensu-ec2-handler"]. +{{< /code >}} + +## Configure an EC2 handler for the service account + +To configure the EC2 handler, you will need AWS account credentials and details for the AWS instance you want to manage, like the AWS instance ID. +You will also need the API key for the `ec2-service` user. + +{{% notice note %}} +**NOTE**: Use [secrets management](../../manage-secrets/secrets-management/) to configure environment variables for your AWS access and secret keys and the `ec2-service` user's API key. +Do not expose this sensitive information by listing it directly in the handler definition.

    +The [Sensu Go EC2 Handler's Bonsai page](https://bonsai.sensu.io/assets/sensu/sensu-ec2-handler#environment-variables) includes an example for configuring secrets definitions with Sensu's [`Env` secrets provider](../../manage-secrets/secrets-providers/#env-secrets-provider-example). +{{% /notice %}} + +In the following code, replace these bracketed placeholders with valid values: + +- ``: the AWS region where your EC2 instance is located. +- ``: the Sensu entity label that contains the AWS instance ID. +If your AWS EC2 instance entities do not include labels that specify the instance ID, use the `aws-instance-id` attribute instead and enter the AWS instance ID itself as the value. +- ``: the Sensu API URL. + +You can also adjust the `aws-allowed-instance-states` value to include any of the Sensu EC2 integration's [available states][10]. +This example lists only "pending" and "running." + +Then, run this command with your valid values in place to create the handler defintion: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +cat << EOF | sensuctl create +--- +type: Handler +api_version: core/v2 +metadata: + name: sensu-ec2-handler +spec: + type: pipe + runtime_assets: + - sensu/sensu-ec2-handler + filters: + - is_incident + - not_silenced + command: >- + sensu-ec2-handler + --aws-region + --aws-instance-id-label + --aws-allowed-instance-states pending,running + --sensu-api-url + secrets: + - name: AWS_ACCESS_KEY_ID + secret: + - name: AWS_SECRET_KEY + secret: + - name: SENSU_API_KEY + secret: +EOF +{{< /code >}} + +{{< code shell "JSON" >}} +cat << EOF | sensuctl create +{ + "type": "Handler", + "api_version": "core/v2", + "metadata": { + "name": "sensu-ec2-handler" + }, + "spec": { + "type": "pipe", + "runtime_assets": [ + "sensu/sensu-ec2-handler" + ], + "filters": [ + "is_incident", + "not_silenced" + ], + "command": "sensu-ec2-handler --aws-region --aws-instance-id-label AWS_INSTANCE_ID_LABEL --aws-allowed-instance-states pending,running --sensu-api-url , + "secrets": [ + { + "name": "AWS_ACCESS_KEY_ID", + "secret": "" + }, + { + "name": "AWS_SECRET_KEY", + "secret": "" + }, + { + "name": "SENSU_API_KEY", + "secret": "" + } + ] + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + +The handler will use the provided AWS credentials to check the specified EC2 instance. +If the instance's status is not "pending" or "running," the handler will use the `ec2-service` user's API key to remove the corresponding entity. + +## Best practices for limited service accounts + +Follow these best practices for creating and managing limited service accounts: + +- Use unique and specific names for limited service accounts. +Names should identify the accounts as limited service accounts as well as the associated services. +- Restrict limited service account access to only the namespaces and role permissions they need to operate properly. +Adjust namespaces and permissions if needed by updating the role or cluster role that is tied to the service account. +- Promptly delete unused limited service accounts to make sure they do not become security risks. + + +[1]: ../rbac/ +[2]: ../rbac#default-users +[3]: ../../../operations/deploy-sensu/install-sensu/#install-the-sensu-backend +[4]: ../rbac/#roles +[5]: ../rbac/#role-bindings +[6]: ../rbac/#rule-attributes +[7]: ../rbac/#users +[8]: ../rbac/#groups +[9]: ../namespaces/ +[10]: https://bonsai.sensu.io/assets/sensu/sensu-ec2-handler#ec2-instance-states +[11]: ../../../operations/deploy-sensu/install-sensu/#install-sensuctl +[12]: ../../../api/#authenticate-with-an-api-key +[13]: https://bonsai.sensu.io/assets/sensu/sensu-ec2-handler +[14]: ../../../plugins/assets/ diff --git a/content/sensu-go/6.12/operations/control-access/create-read-only-user.md b/content/sensu-go/6.12/operations/control-access/create-read-only-user.md new file mode 100644 index 0000000000..381ca30840 --- /dev/null +++ b/content/sensu-go/6.12/operations/control-access/create-read-only-user.md @@ -0,0 +1,289 @@ +--- +title: "Create a read-only user with role-based access control" +linkTitle: "Create a Read-only User" +guide_title: "Create a read-only user with role-based access control" +type: "guide" +description: "Use Sensu's role-based access control (RBAC) to assign read-only access to users and achieve multitenancy so projects and teams can share a Sensu instance." +weight: 30 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: control-access +--- + +Role-based access control (RBAC) allows you to exercise fine-grained control over how Sensu users interact with Sensu resources. +Use RBAC rules to achieve **multitenancy** so different projects and teams can share a Sensu instance. + +Sensu RBAC helps different teams and projects share a Sensu instance. +RBAC allows you to manage users and their access to resources based on **namespaces**, **groups**, **roles**, and **bindings**. + +By default, Sensu includes a `default` namespace and an `admin` user with full permissions to create, modify, and delete resources within Sensu, including RBAC resources like users and roles. + +## Requirements + +This guide requires a running Sensu [backend][5] and a [sensuctl][6] instance configured to connect to the backend as the [`admin` user][2]. + +## Create a read-only user + +In this section, you'll create a user and assign them read-only access to resources within the `default` namespace using a **role** and a **role binding**. + +1. Create a user with the username `alice` and assign them to the group `ops`: +{{< code shell >}} +sensuctl user create alice --password='password' --groups=ops +{{< /code >}} + + This command creates the following user: + {{< language-toggle >}} +{{< code text "YAML" >}} +username: alice +groups: +- ops +disabled: false +{{< /code >}} +{{< code text "JSON" >}} +{ + "username": "alice", + "groups": [ + "ops" + ], + "disabled": false +} +{{< /code >}} +{{< /language-toggle >}} + +2. Create a `read-only` role with `get` and `list` permissions for all resources (`*`) within the `default` namespace: +{{< code shell >}} +sensuctl role create read-only --verb=get,list --resource=* --namespace=default +{{< /code >}} + + This command creates the following role resource definition: + + {{< language-toggle >}} +{{< code text "YAML" >}} +--- +type: Role +api_version: core/v2 +metadata: + name: read-only +spec: + rules: + - resource_names: null + resources: + - '*' + verbs: + - get + - list +{{< /code >}} +{{< code text "JSON" >}} +{ + "type": "Role", + "api_version": "core/v2", + "metadata": { + "name": "read-only" + }, + "spec": { + "rules": [ + { + "resource_names": null, + "resources": [ + "*" + ], + "verbs": [ + "get", + "list" + ] + } + ] + } +} +{{< /code >}} +{{< /language-toggle >}} + +3. Create an `ops-read-only` role binding to assign the `read-only` role to the `ops` group: +{{< code shell >}} +sensuctl role-binding create ops-read-only --role=read-only --group=ops +{{< /code >}} + + This command creates the following role binding resource definition: + {{< language-toggle >}} +{{< code text "YAML" >}} +--- +type: RoleBinding +api_version: core/v2 +metadata: + name: ops-read-only +spec: + role_ref: + name: read-only + type: Role + subjects: + - name: ops + type: Group +{{< /code >}} +{{< code text "JSON" >}} +{ + "type": "RoleBinding", + "api_version": "core/v2", + "metadata": { + "name": "ops-read-only" + }, + "spec": { + "role_ref": { + "name": "read-only", + "type": "Role" + }, + "subjects": [ + { + "name": "ops", + "type": "Group" + } + ] + } +} +{{< /code >}} +{{< /language-toggle >}} + +All users in the `ops` group now have read-only access to all resources within the default namespace. +You can also use role bindings to tie roles directly to users using the `--user` flag. + +To manage your RBAC configuration, use the `sensuctl user`, `sensuctl role`, and `sensuctl role-binding` commands. + +## Create a cluster-wide event-reader user + +Suppose you want to create a user with read-only access to events across all namespaces. +Because you want this role to have cluster-wide permissions, you'll need to create a **cluster role** and a **cluster role binding**. + +1. Create a user with the username `bob` and assign them to the group `ops`: +{{< code shell >}} +sensuctl user create bob --password='password' --groups=ops +{{< /code >}} + + This command creates the following user: + {{< language-toggle >}} +{{< code text "YAML" >}} +username: bob +groups: +- ops +disabled: false +{{< /code >}} +{{< code text "JSON" >}} +{ + "username": "bob", + "groups": [ + "ops" + ], + "disabled": false +} +{{< /code >}} +{{< /language-toggle >}} + +2. Create a `global-event-reader` cluster role with `get` and `list` permissions for `events` across all namespaces: +{{< code shell >}} +sensuctl cluster-role create global-event-reader --verb=get,list --resource=events +{{< /code >}} + + This command creates the following cluster role resource definition: + + {{< language-toggle >}} +{{< code text "YAML" >}} +--- +type: ClusterRole +api_version: core/v2 +metadata: + name: global-event-reader +spec: + rules: + - resource_names: null + resources: + - events + verbs: + - get + - list +{{< /code >}} +{{< code text "JSON" >}} +{ + "type": "ClusterRole", + "api_version": "core/v2", + "metadata": { + "name": "global-event-reader" + }, + "spec": { + "rules": [ + { + "resource_names": null, + "resources": [ + "events" + ], + "verbs": [ + "get", + "list" + ] + } + ] + } +} +{{< /code >}} +{{< /language-toggle >}} + +3. Create an `ops-event-reader` cluster role binding to assign the `global-event-reader` role to the `ops` group: +{{< code shell >}} +sensuctl cluster-role-binding create ops-event-reader --cluster-role=global-event-reader --group=ops +{{< /code >}} + + This command creates the following cluster role binding resource definition: + + {{< language-toggle >}} +{{< code text "YAML" >}} +--- +type: ClusterRoleBinding +api_version: core/v2 +metadata: + name: ops-event-reader +spec: + role_ref: + name: global-event-reader + type: ClusterRole + subjects: + - name: ops + type: Group +{{< /code >}} +{{< code text "JSON" >}} +{ + "type": "ClusterRoleBinding", + "api_version": "core/v2", + "metadata": { + "name": "ops-event-reader" + }, + "spec": { + "role_ref": { + "name": "global-event-reader", + "type": "ClusterRole" + }, + "subjects": [ + { + "name": "ops", + "type": "Group" + } + ] + } +} +{{< /code >}} +{{< /language-toggle >}} + +All users in the `ops` group now have read-only access to events across all namespaces. + +## What's next + +Now that you know how to create a user, a role, and a role binding to assign a role to a user, check out the [RBAC reference][1] for in-depth documentation on role-based access control, examples, and information about cluster-wide permissions. + +Read about [monitoring as code][3] with Sensu and learn how to [use SensuFlow][4] to synchronize your monitoring and observability code with your Sensu deployments. + + +[1]: ../rbac/ +[2]: ../rbac#default-users +[3]: ../../monitoring-as-code/ +[4]: https://sensu.io/blog/monitoring-as-code-with-sensu-flow +[5]: ../../../operations/deploy-sensu/install-sensu/#install-the-sensu-backend +[6]: ../../../operations/deploy-sensu/install-sensu/#install-sensuctl diff --git a/content/sensu-go/6.12/operations/control-access/ldap-auth.md b/content/sensu-go/6.12/operations/control-access/ldap-auth.md new file mode 100644 index 0000000000..413b7af442 --- /dev/null +++ b/content/sensu-go/6.12/operations/control-access/ldap-auth.md @@ -0,0 +1,957 @@ +--- +title: "Lightweight Directory Access Protocol (LDAP) reference" +linkTitle: "LDAP Reference" +reference_title: "Lightweight Directory Access Protocol (LDAP)" +type: "reference" +description: "Read this reference to configure single sign-on (SSO) authentication for Sensu using Lightweight Directory Access Protocol (LDAP)." +weight: 55 +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: control-access +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access Lightweight Directory Access Protocol (LDAP) authentication for single sign-on (SSO) in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} + +Sensu requires username and password authentication to access the [web UI][1], [API][8], and [sensuctl][2] command line tool. + +In addition to the [built-in basic authentication][4], Sensu offers [commercial support][6] for a standards-compliant Lightweight Directory Access Protocol (LDAP) tool for single sign-on (SSO) authentication. +The Sensu LDAP authentication provider is tested with [OpenLDAP][7]. +If you're using AD, head to the [AD section][37]. + +For general information about configuring authentication providers, read [Configure single sign-on (SSO) authentication][12]. + +## LDAP configuration examples + +**Example LDAP configuration: Minimum required attributes** + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: ldap +api_version: authentication/v2 +metadata: + name: openldap +spec: + servers: + - group_search: + base_dn: dc=acme,dc=org + host: 127.0.0.1 + user_search: + base_dn: dc=acme,dc=org +{{< /code >}} + +{{< code json >}} +{ + "type": "ldap", + "api_version": "authentication/v2", + "spec": { + "servers": [ + { + "host": "127.0.0.1", + "group_search": { + "base_dn": "dc=acme,dc=org" + }, + "user_search": { + "base_dn": "dc=acme,dc=org" + } + } + ] + }, + "metadata": { + "name": "openldap" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +**Example LDAP configuration: All attributes** + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: ldap +api_version: authentication/v2 +metadata: + name: openldap +spec: + allowed_groups: [] + groups_prefix: ldap + servers: + - binding: + password: YOUR_PASSWORD + user_dn: cn=binder,dc=acme,dc=org + client_cert_file: /path/to/ssl/cert.pem + client_key_file: /path/to/ssl/key.pem + group_search: + attribute: member + base_dn: dc=acme,dc=org + name_attribute: cn + object_class: groupOfNames + host: 127.0.0.1 + insecure: false + port: 636 + security: tls + trusted_ca_file: /path/to/trusted-certificate-authorities.pem + user_search: + attribute: uid + base_dn: dc=acme,dc=org + name_attribute: cn + object_class: person + username_prefix: ldap +{{< /code >}} + +{{< code json >}} +{ + "type": "ldap", + "api_version": "authentication/v2", + "spec": { + "servers": [ + { + "host": "127.0.0.1", + "port": 636, + "insecure": false, + "security": "tls", + "trusted_ca_file": "/path/to/trusted-certificate-authorities.pem", + "client_cert_file": "/path/to/ssl/cert.pem", + "client_key_file": "/path/to/ssl/key.pem", + "binding": { + "user_dn": "cn=binder,dc=acme,dc=org", + "password": "YOUR_PASSWORD" + }, + "group_search": { + "base_dn": "dc=acme,dc=org", + "attribute": "member", + "name_attribute": "cn", + "object_class": "groupOfNames" + }, + "user_search": { + "base_dn": "dc=acme,dc=org", + "attribute": "uid", + "name_attribute": "cn", + "object_class": "person" + } + } + ], + "allowed_groups": [], + "groups_prefix": "ldap", + "username_prefix": "ldap" + }, + "metadata": { + "name": "openldap" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +{{% notice note %}} +**NOTE**: If you specify allowed groups, the group names must exactly match the names the authentication provider returns to the Sensu backend. +{{% /notice %}} + +**Example LDAP configuration: Use `memberOf` attribute instead of `group_search`** + +If your LDAP server is configured to return a `memberOf` attribute when you perform a query, you can use `memberOf` in your Sensu LDAP implementation instead of `group_search`. +The `memberOf` attribute contains the user's group membership, which effectively removes the requirement to look up the user's groups. + +To use the `memberOf` attribute in your LDAP implementation, remove the `group_search` object from your LDAP config: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: ldap +api_version: authentication/v2 +metadata: + name: openldap +spec: + servers: + host: 127.0.0.1 + user_search: + base_dn: dc=acme,dc=org +{{< /code >}} + +{{< code json >}} +{ + "type": "ldap", + "api_version": "authentication/v2", + "spec": { + "servers": [ + { + "host": "127.0.0.1", + "user_search": { + "base_dn": "dc=acme,dc=org" + } + } + ] + }, + "metadata": { + "name": "openldap" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +After you configure LDAP to use the `memberOf` attribute, the `debug` log level will include the following log entries: + +{{< code text >}} +{"component":"authentication/v2","level":"debug","msg":"using the \"memberOf\" attribute to determine the group membership of user \"user1\"","time":"2020-06-25T14:10:58-04:00"} +{"component":"authentication/v2","level":"debug","msg":"found 1 LDAP group(s): [\"sensu\"]","time":"2020-06-25T14:10:58-04:00"} +{{< /code >}} + +## LDAP specification + +### Top-level attributes + +type | +-------------|------ +description | Top-level attribute that specifies the [`sensuctl create`][38] resource type. For LDAP definitions, the `type` should always be `ldap`. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +type: ldap +{{< /code >}} +{{< code json >}} +{ + "type": "ldap" +} +{{< /code >}} +{{< /language-toggle >}} + +api_version | +-------------|------ +description | Top-level attribute that specifies the Sensu API group and version. For LDAP definitions, the `api_version` should always be `authentication/v2`. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +api_version: authentication/v2 +{{< /code >}} +{{< code json >}} +{ + "api_version": "authentication/v2" +} +{{< /code >}} +{{< /language-toggle >}} + +metadata | +-------------|------ +description | Top-level map that contains the LDAP definition `name`. Review the [metadata attributes][24] for details. +required | true +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +metadata: + name: openldap +{{< /code >}} +{{< code json >}} +{ + "metadata": { + "name": "openldap" + } +} +{{< /code >}} +{{< /language-toggle >}} + +spec | +-------------|------ +description | Top-level map that includes the LDAP [spec attributes][39]. +required | true +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +spec: + servers: + - host: 127.0.0.1 + port: 636 + insecure: false + security: tls + trusted_ca_file: "/path/to/trusted-certificate-authorities.pem" + client_cert_file: "/path/to/ssl/cert.pem" + client_key_file: "/path/to/ssl/key.pem" + binding: + user_dn: cn=binder,dc=acme,dc=org + password: YOUR_PASSWORD + group_search: + base_dn: dc=acme,dc=org + attribute: member + name_attribute: cn + object_class: groupOfNames + user_search: + base_dn: dc=acme,dc=org + attribute: uid + name_attribute: cn + object_class: person + allowed_groups: [] + groups_prefix: ldap + username_prefix: ldap + +{{< /code >}} +{{< code json >}} +{ + "spec": { + "servers": [ + { + "host": "127.0.0.1", + "port": 636, + "insecure": false, + "security": "tls", + "trusted_ca_file": "/path/to/trusted-certificate-authorities.pem", + "client_cert_file": "/path/to/ssl/cert.pem", + "client_key_file": "/path/to/ssl/key.pem", + "binding": { + "user_dn": "cn=binder,dc=acme,dc=org", + "password": "YOUR_PASSWORD" + }, + "group_search": { + "base_dn": "dc=acme,dc=org", + "attribute": "member", + "name_attribute": "cn", + "object_class": "groupOfNames" + }, + "user_search": { + "base_dn": "dc=acme,dc=org", + "attribute": "uid", + "name_attribute": "cn", + "object_class": "person" + } + } + ], + "allowed_groups": [], + "groups_prefix": "ldap", + "username_prefix": "ldap" + } +} +{{< /code >}} +{{< /language-toggle >}} + +### LDAP metadata attributes + +| name | | +-------------|------ +description | A unique string used to identify the LDAP configuration. Names cannot contain special characters or spaces (validated with Go regex [`\A[\w\.\-]+\z`][42]). +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +name: openldap +{{< /code >}} +{{< code json >}} +{ + "name": "openldap" +} +{{< /code >}} +{{< /language-toggle >}} + +### LDAP spec attributes + +| servers | | +-------------|------ +description | The list of [LDAP servers][40] to use. During the authentication process, Sensu attempts to authenticate against each LDAP server in sequence until authentication is successful or there are no more servers to try. +required | true +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +servers: +- host: 127.0.0.1 + port: 636 + insecure: false + security: tls + trusted_ca_file: "/path/to/trusted-certificate-authorities.pem" + client_cert_file: "/path/to/ssl/cert.pem" + client_key_file: "/path/to/ssl/key.pem" + binding: + user_dn: cn=binder,dc=acme,dc=org + password: YOUR_PASSWORD + group_search: + base_dn: dc=acme,dc=org + attribute: member + name_attribute: cn + object_class: groupOfNames + user_search: + base_dn: dc=acme,dc=org + attribute: uid + name_attribute: cn + object_class: person +{{< /code >}} +{{< code json >}} +{ + "servers": [ + { + "host": "127.0.0.1", + "port": 636, + "insecure": false, + "security": "tls", + "trusted_ca_file": "/path/to/trusted-certificate-authorities.pem", + "client_cert_file": "/path/to/ssl/cert.pem", + "client_key_file": "/path/to/ssl/key.pem", + "binding": { + "user_dn": "cn=binder,dc=acme,dc=org", + "password": "YOUR_PASSWORD" + }, + "group_search": { + "base_dn": "dc=acme,dc=org", + "attribute": "member", + "name_attribute": "cn", + "object_class": "groupOfNames" + }, + "user_search": { + "base_dn": "dc=acme,dc=org", + "attribute": "uid", + "name_attribute": "cn", + "object_class": "person" + } + } + ] +} +{{< /code >}} +{{< /language-toggle >}} + + + +| allowed_groups | | +-------------|------ +description | An array of allowed LDAP group strings to include in the tokenized identity claim. Use to specify which groups to encode in the authentication provider's JSON Web Token (JWT) when the authenticated LDAP user is a member of many groups and the tokenized identity claim would be too large for correct web client operation.{{% notice note %}}**NOTE**: Allowed group names are case-sensitive and must exactly match the group names the authentication provider returns to the Sensu backend. +{{% /notice %}} +required | false +type | Array of strings +example | {{< language-toggle >}} +{{< code yml >}} +allowed_groups: +- Sensu_Viewers +- Sensu_Operators +{{< /code >}} +{{< code json >}} +{ + "allowed_groups": [ + "Sensu_Viewers", + "Sensu_Operators" + ] +} +{{< /code >}} +{{< /language-toggle >}} + + + +| groups_prefix | | +-------------|------ +description | The prefix added to all LDAP groups. Sensu appends the groups_prefix with a colon. For example, for the groups_prefix `ldap` and the group `dev`, the resulting group name in Sensu is `ldap:dev`. Use the groups_prefix when integrating LDAP groups with Sensu RBAC [role bindings and cluster role bindings][13]. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +groups_prefix: ldap +{{< /code >}} +{{< code json >}} +{ + "groups_prefix": "ldap" +} +{{< /code >}} +{{< /language-toggle >}} + + + +| username_prefix | | +-------------|------ +description | The prefix added to all LDAP usernames. Sensu appends the username_prefix with a colon. For example, for the username_prefix `ldap` and the user `alice`, the resulting username in Sensu is `ldap:alice`. Use the username_prefix when integrating LDAP users with Sensu RBAC [role bindings and cluster role bindings][13]. Users _do not_ need to provide the username_prefix when logging in to Sensu. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +username_prefix: ldap +{{< /code >}} +{{< code json >}} +{ + "username_prefix": "ldap" +} +{{< /code >}} +{{< /language-toggle >}} + +### LDAP server attributes + +| host | | +-------------|------ +description | LDAP server IP address or [fully qualified domain name (FQDN)][41]. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +host: 127.0.0.1 +{{< /code >}} +{{< code json >}} +{ + "host": "127.0.0.1" +} +{{< /code >}} +{{< /language-toggle >}} + +| port | | +-------------|------ +description | LDAP server port. +required | true +type | Integer +default | `389` for insecure connections; `636` for TLS connections +example | {{< language-toggle >}} +{{< code yml >}} +port: 636 +{{< /code >}} +{{< code json >}} +{ + "port": 636 +} +{{< /code >}} +{{< /language-toggle >}} + + + +| insecure | | +-------------|------ +description | Skips SSL certificate verification when set to `true`. {{% notice warning %}} +**WARNING**: Do not use an insecure connection in production environments. +{{% /notice %}} +required | false +type | Boolean +default | `false` +example | {{< language-toggle >}} +{{< code yml >}} +insecure: false +{{< /code >}} +{{< code json >}} +{ + "insecure": false +} +{{< /code >}} +{{< /language-toggle >}} + + + +| security | | +-------------|------ +description | Determines the encryption type to be used for the connection to the LDAP server: `insecure` (unencrypted connection; not recommended for production), `tls` (secure encrypted connection), or `starttls` (unencrypted connection upgrades to a secure connection). +type | String +default | `tls` +example | {{< language-toggle >}} +{{< code yml >}} +security: tls +{{< /code >}} +{{< code json >}} +{ + "security": "tls" +} +{{< /code >}} +{{< /language-toggle >}} + +| trusted_ca_file | | +-------------|------ +description | Path to an alternative CA bundle file in PEM format to be used instead of the system's default bundle. This CA bundle is used to verify the server's certificate. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +trusted_ca_file: /path/to/trusted-certificate-authorities.pem +{{< /code >}} +{{< code json >}} +{ + "trusted_ca_file": "/path/to/trusted-certificate-authorities.pem" +} +{{< /code >}} +{{< /language-toggle >}} + +| client_cert_file | | +-------------|------ +description | Path to the certificate that should be sent to the server if requested. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +client_cert_file: /path/to/ssl/cert.pem +{{< /code >}} +{{< code json >}} +{ + "client_cert_file": "/path/to/ssl/cert.pem" +} +{{< /code >}} +{{< /language-toggle >}} + +| client_key_file | | +-------------|------ +description | Path to the key file associated with the `client_cert_file`. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +client_key_file: /path/to/ssl/key.pem +{{< /code >}} +{{< code json >}} +{ + "client_key_file": "/path/to/ssl/key.pem" +} +{{< /code >}} +{{< /language-toggle >}} + + + +| binding | | +-------------|------ +description | The LDAP account that performs user and group lookups. If your server supports anonymous binding, you can omit the `user_dn` or `password` attributes to query the directory without credentials. Review the [binding attributes][43] for details. +required | false +type | Map +example | {{< language-toggle >}} +{{< code yml >}} +binding: + user_dn: cn=binder,dc=acme,dc=org + password: YOUR_PASSWORD +{{< /code >}} +{{< code json >}} +{ + "binding": { + "user_dn": "cn=binder,dc=acme,dc=org", + "password": "YOUR_PASSWORD" + } +} +{{< /code >}} +{{< /language-toggle >}} + +| group_search | | +-------------|------ +description | Search configuration for groups. Review the [group search attributes][21] for more information. Remove the `group_search` object from your configuration to use the `memberOf` attribute instead. +required | false +type | Map +example | {{< language-toggle >}} +{{< code yml >}} +group_search: + base_dn: dc=acme,dc=org + attribute: member + name_attribute: cn + object_class: groupOfNames +{{< /code >}} +{{< code json >}} +{ + "group_search": { + "base_dn": "dc=acme,dc=org", + "attribute": "member", + "name_attribute": "cn", + "object_class": "groupOfNames" + } +} +{{< /code >}} +{{< /language-toggle >}} + + + +| user_search | | +-------------|------ +description | Search configuration for users. Review the [user search attributes][22] for more information. +required | true +type | Map +example | {{< language-toggle >}} +{{< code yml >}} +user_search: + base_dn: dc=acme,dc=org + attribute: uid + name_attribute: cn + object_class: person +{{< /code >}} +{{< code json >}} +{ + "user_search": { + "base_dn": "dc=acme,dc=org", + "attribute": "uid", + "name_attribute": "cn", + "object_class": "person" + } +} +{{< /code >}} +{{< /language-toggle >}} + +### LDAP binding attributes + +| user_dn | | +-------------|------ +description | The LDAP account that performs user and group lookups. We recommend using a read-only account. Use the distinguished name (DN) format, such as `cn=binder,cn=users,dc=domain,dc=tld`. If your server supports anonymous binding, you can omit this attribute to query the directory without credentials. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +user_dn: cn=binder,dc=acme,dc=org +{{< /code >}} +{{< code json >}} +{ + "user_dn": "cn=binder,dc=acme,dc=org" +} +{{< /code >}} +{{< /language-toggle >}} + +| password | | +-------------|------ +description | Password for the `user_dn` account. If your server supports anonymous binding, you can omit this attribute to query the directory without credentials. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +password: YOUR_PASSWORD +{{< /code >}} +{{< code json >}} +{ + "password": "YOUR_PASSWORD" +} +{{< /code >}} +{{< /language-toggle >}} + +### LDAP group search attributes + +| base_dn | | +-------------|------ +description | Tells Sensu which part of the directory tree to search. For example, `dc=acme,dc=org` searches within the `acme.org` directory. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +base_dn: dc=acme,dc=org +{{< /code >}} +{{< code json >}} +{ + "base_dn": "dc=acme,dc=org" +} +{{< /code >}} +{{< /language-toggle >}} + +| attribute | | +-------------|------ +description | Used for comparing result entries. Combined with other filters as
    `"(=)"`. +required | false +type | String +default | `member` +example | {{< language-toggle >}} +{{< code yml >}} +attribute: member +{{< /code >}} +{{< code json >}} +{ + "attribute": "member" +} +{{< /code >}} +{{< /language-toggle >}} + + + +| name_attribute | | +-------------|------ +description | Represents the attribute to use as the entry name. +required | false +type | String +default | `cn` +example | {{< language-toggle >}} +{{< code yml >}} +name_attribute: cn +{{< /code >}} +{{< code json >}} +{ + "name_attribute": "cn" +} +{{< /code >}} +{{< /language-toggle >}} + +| object_class | | +-------------|------ +description | Identifies the class of objects returned in the search result. Combined with other filters as `"(objectClass=)"`. +required | false +type | String +default | `groupOfNames` +example | {{< language-toggle >}} +{{< code yml >}} +object_class: groupOfNames +{{< /code >}} +{{< code json >}} +{ + "object_class": "groupOfNames" +} +{{< /code >}} +{{< /language-toggle >}} + +### LDAP user search attributes + +| base_dn | | +-------------|------ +description | Tells Sensu which part of the directory tree to search. For example, `dc=acme,dc=org` searches within the `acme.org` directory. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +base_dn: dc=acme,dc=org +{{< /code >}} +{{< code json >}} +{ + "base_dn": "dc=acme,dc=org" +} +{{< /code >}} +{{< /language-toggle >}} + +| attribute | | +-------------|------ +description | Used for comparing result entries. Combined with other filters as
    `"(=)"`. +required | false +type | String +default | `uid` +example | {{< language-toggle >}} +{{< code yml >}} +attribute: uid +{{< /code >}} +{{< code json >}} +{ + "attribute": "uid" +} +{{< /code >}} +{{< /language-toggle >}} + +| name_attribute | | +-------------|------ +description | Represents the attribute to use as the entry name +required | false +type | String +default | `cn` +example | {{< language-toggle >}} +{{< code yml >}} +name_attribute: cn +{{< /code >}} +{{< code json >}} +{ + "name_attribute": "cn" +} +{{< /code >}} +{{< /language-toggle >}} + +| object_class | | +-------------|------ +description | Identifies the class of objects returned in the search result. Combined with other filters as `"(objectClass=)"`. +required | false +type | String +default | `person` +example | {{< language-toggle >}} +{{< code yml >}} +object_class: person +{{< /code >}} +{{< code json >}} +{ + "object_class": "person" +} +{{< /code >}} +{{< /language-toggle >}} + +## LDAP troubleshooting + +To troubleshoot any issue with LDAP authentication, start by [increasing the log verbosity][3] of sensu-backend to the [debug log level][5]. +Most authentication and authorization errors are only displayed on the debug log level to avoid flooding the log files. + +{{% notice note %}} +**NOTE**: If you can't locate any log entries referencing LDAP authentication, run [sensuctl auth list](../sso/#manage-authentication-providers) to make sure that you successfully installed the LDAP provider. +{{% /notice %}} + +### Authentication + +This section lists common authentication error messages and describes possible solutions for each of them. + +#### `failed to connect: LDAP Result Code 200 "Network Error"` + +The LDAP provider couldn't establish a TCP connection to the LDAP server. +Verify the `host` and `port` attributes. +If you are not using LDAP over TLS/SSL, make sure to set the value of the [`security` attribute][10] to `insecure` for plaintext communication. + +#### `certificate signed by unknown authority` + +If you are using a self-signed certificate, make sure to set the [`insecure` attribute][11] to `true`. +This will bypass verification of the certificate's signing authority. + +#### `failed to bind: ...` + +The first step for authenticating a user with the LDAP provider is to bind to the LDAP server using the service account specified in the [`binding` object][14]. +Make sure the [`user_dn` attribute][43] specifies a valid **DN** and that its password is correct. + +#### `user was not found` + +The user search failed. +No user account could be found with the given username. +Check the [`user_search` object][15] and make sure that: + +- The specified `base_dn` contains the requested user entry DN +- The specified `attribute` contains the _username_ as its value in the user entry +- The `object_class` attribute corresponds to the user entry object class + +#### `ldap search for user returned x results, expected only 1` + +The user search returned more than one user entry, so the provider could not determine which of these entries to use. +Change the [`user_search` object][15] so the provided `username` can be used to uniquely identify a user entry. +Here are two methods to try: + +- Adjust the `attribute` so its value (which corresponds to the `username`) is unique among the user entries +- Adjust the `base_dn` so it only includes one of the user entries + +#### `ldap entry missing required attribute ` + +The user entry returned (identified by ``) doesn't include the attribute specified by [`name_attribute` object][9], so the LDAP provider could not determine which attribute to use as the username in the user entry. +Adjust the `name_attribute` so it specifies a human-readable name for the user. + +#### `ldap group entry missing and cn attributes` + +The group search returned a group entry (identified by ``) that doesn't have the [`name_attribute` object][9] or a `cn` attribute, so the LDAP provider could not determine which attribute to use as the group name in the group entry. +Adjust the `name_attribute` so it specifies a human-readable name for the group. + +### Authorization + +Once authenticated, each user needs to be granted permissions via either a `ClusterRoleBinding` or a `RoleBinding`. + +The way LDAP users and LDAP groups can be referred as subjects of a cluster role or role binding depends on the [`groups_prefix`][16] and [`username_prefix`][17] configuration attributes values of the LDAP provider. +For example, for the groups_prefix `ldap` and the group `dev`, the resulting group name in Sensu is `ldap:dev`. + +#### Permissions are not granted via the LDAP group(s) + +During authentication, the LDAP provider will print all groups found in LDAP (for example, `found 1 group(s): [dev]`) in the logs. +Keep in mind that this group name does not contain the [`groups_prefix`][16] at this point. + +The Sensu backend logs each attempt made to authorize an RBAC request. +This is useful for determining why a specific binding didn't grant the request. +For example: + +{{< code text >}} +[...] the user is not a subject of the ClusterRoleBinding cluster-admin [...] +[...] could not authorize the request with the ClusterRoleBinding system:user [...] +[...] could not authorize the request with any ClusterRoleBindings [...] +{{< /code >}} + + +[1]: ../../../web-ui/ +[2]: ../../../sensuctl/ +[3]: ../../maintain-sensu/troubleshoot/#increment-log-level-verbosity +[4]: ../#use-built-in-basic-authentication +[5]: ../../maintain-sensu/troubleshoot/#log-levels +[6]: ../../../commercial/ +[7]: https://www.openldap.org/ +[8]: ../../../api/ +[9]: #name-attribute-attribute +[10]: #security-attribute +[11]: #insecure-attribute +[12]: ../sso/ +[13]: ../rbac#role-bindings-and-cluster-role-bindings +[14]: #binding-attribute +[15]: #user-search-attribute +[16]: #groups-prefix +[17]: #username-prefix +[21]: #ldap-group-search-attributes +[22]: #ldap-user-search-attributes +[24]: #ldap-metadata-attributes +[37]: ../ad-auth/ +[38]: ../../../sensuctl/create-manage-resources/#create-resources +[39]: #ldap-spec-attributes +[40]: #ldap-server-attributes +[41]: https://en.wikipedia.org/wiki/Fully_qualified_domain_name +[42]: https://regex101.com/r/zo9mQU/2 +[43]: #ldap-binding-attributes diff --git a/content/sensu-go/6.12/operations/control-access/namespaces.md b/content/sensu-go/6.12/operations/control-access/namespaces.md new file mode 100644 index 0000000000..bb5a4bfedd --- /dev/null +++ b/content/sensu-go/6.12/operations/control-access/namespaces.md @@ -0,0 +1,232 @@ +--- +title: "Namespaces reference" +linkTitle: "Namespaces Reference" +reference_title: "Namespaces" +type: "reference" +description: "Use namespaces with Sensu's role-based access control to allow teams and projects to share a Sensu instance and authorize access to Sensu resources." +weight: 75 +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: control-access +--- + +Namespaces partition resources within Sensu. +Sensu entities, checks, handlers, and other [namespaced resources][5] belong to a single namespace. + +Namespaces help teams use different resources (like entities, checks, and handlers) within Sensu and impose their own controls on those resources. +A Sensu instance can have multiple namespaces, each with their own set of managed resources. +Resource names must be unique within a namespace but do not need to be unique across namespaces. + +Namespace configuration applies to [sensuctl][2], the [API][6], and the [web UI][3]. +To create and manage namespaces, [configure sensuctl][9] as the [default `admin` user][7] or create a [cluster role][8] with `namespaces` permissions. + +## Namespace example + +This example shows the resource definition for a `production` namespace. +You can use this example with [`sensuctl create`][10] to create a `production` namespace in your Sensu deployment: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Namespace +api_version: core/v2 +metadata: {} +spec: + name: production +{{< /code >}} + +{{< code json >}} +{ + "type": "Namespace", + "api_version": "core/v2", + "metadata": {}, + "spec": { + "name": "production" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Best practices for namespaces + +**Use namespaces for isolation, not organization** + +Use namespaces to enforce full isolation of different groups of resources, not to organize resources. +An agent cannot belong to two namespaces or execute checks in two different namespaces. +To organize resources, use labels rather than multiple namespaces. + +## Default namespaces + +Every [Sensu backend][1] includes a `default` namespace. +All resources created without a specified namespace are created within the `default` namespace. + +At startup, Sensu also creates the `sensu-system` namespace to contain [backend entities][12]. +The `sensu-system` namespace and backend entities facilitate backend error reporting and make Sensu deployments more observable by enabling backend-generated status and metrics events. + +Only cluster admins have access to the `sensu-system` namespace. +If you have cluster admin permissions, you can use [sensuctl][2] and the [web UI][3] to access backend entities like other entities. + +## Assign a resource to a namespace + +You can assign a resource to a namespace in the resource definition. +Only resources that belong to a [namespaced resource type][5] (like checks, filters, and handlers) can be assigned to a namespace. + +For example, to assign a check called `check-cpu` to the `production` namespace, include the `namespace` attribute in the check definition: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: check-cpu + namespace: production +spec: + check_hooks: null + command: check-cpu.sh -w 75 -c 90 + handlers: + - slack + interval: 30 + subscriptions: + - system + timeout: 0 + ttl: 0 +{{< /code >}} + +{{< code json >}} +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "check-cpu", + "namespace": "production" + }, + "spec": { + "check_hooks": null, + "command": "check-cpu.sh -w 75 -c 90", + "handlers": ["slack"], + "interval": 30, + "subscriptions": ["system"], + "timeout": 0, + "ttl": 0 + } +} +{{< /code >}} + +{{< /language-toggle >}} + +Read the [reference docs][4] for the corresponding [resource type][5] to create resource definitions. + +{{% notice protip %}} +**PRO TIP**: If you omit the `namespace` attribute from resource definitions, you can use the `senusctl create --namespace` flag to specify the namespace for a group of resources at the time of creation. +This allows you to replicate resources across namespaces without manual editing.

    +Read the sensuctl documentation for more information about [creating resources across namespaces](../../../sensuctl/create-manage-resources/#create-resources-across-namespaces) and [using the sensuctl namespace command](../../../sensuctl/create-manage-resources/#use-the-sensuctl-namespace-command). +{{% /notice %}} + +## Namespace specification + +### Top-level attributes + +api_version | +-------------|------ +description | Top-level attribute that specifies the Sensu API group and version. The `api_version` should always be `core/v2`. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +api_version: core/v2 +{{< /code >}} +{{< code json >}} +{ + "api_version": "core/v2" +} +{{< /code >}} +{{< /language-toggle >}} + +metadata | +-------------|------ +description | Top-level collection of metadata about the namespace. For namespaces, the metatdata should always be empty. +required | true +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +metadata: {} +{{< /code >}} +{{< code json >}} +{ + "metadata": {} +} +{{< /code >}} +{{< /language-toggle >}} + +spec | +-------------|------ +description | Top-level map that includes the namespace's [spec attributes][11]. +required | true +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +spec: + name: production +{{< /code >}} +{{< code json >}} +{ + "spec": { + "name": "production" + } +} +{{< /code >}} +{{< /language-toggle >}} + +type | +-------------|------ +description | Top-level attribute that specifies the resource type. Namespaces should always be type `Namespace`. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +type: Namespace +{{< /code >}} +{{< code json >}} +{ + "type": "Namespace" +} +{{< /code >}} +{{< /language-toggle >}} + +### Spec attributes + +name | +-------------|------ +description | Name of the namespace. Namespace names can contain alphanumeric characters and hyphens and must begin and end with an alphanumeric character. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +name: production +{{< /code >}} +{{< code json >}} +{ + "name": "production" +} +{{< /code >}} +{{< /language-toggle >}} + + +[1]: ../../../observability-pipeline/observe-schedule/backend/ +[2]: ../../../sensuctl/ +[3]: ../../../web-ui/ +[4]: ../../../reference/ +[5]: ../rbac/#namespaced-resource-types +[6]: ../../../api/ +[7]: ../rbac/#default-users +[8]: ../rbac/#roles-and-cluster-roles +[9]: ../../deploy-sensu/install-sensu/#install-sensuctl +[10]: ../../../sensuctl/create-manage-resources/#create-resources +[11]: #spec-attributes +[12]: ../../../observability-pipeline/observe-entities/entities/#backend-entities diff --git a/content/sensu-go/6.12/operations/control-access/oidc-auth.md b/content/sensu-go/6.12/operations/control-access/oidc-auth.md new file mode 100644 index 0000000000..1b5c91a2c0 --- /dev/null +++ b/content/sensu-go/6.12/operations/control-access/oidc-auth.md @@ -0,0 +1,592 @@ +--- +title: "OpenID Connect 1.0 protocol (OIDC) reference" +linkTitle: "OIDC Reference" +reference_title: "OpenID Connect 1.0 protocol (OIDC)" +type: "reference" +description: "Read this reference to configure single sign-on (SSO) authentication for Sensu using OpenID Connect 1.0 protocol (OIDC)." +weight: 60 +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: control-access +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access OpenID Connect 1.0 protocol (OIDC) authentication for single sign-on (SSO) in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} + +Sensu requires username and password authentication to access the [web UI][1], [API][8], and [sensuctl][2] command line tool. + +In addition to the [built-in basic authentication][7], Sensu offers [commercial support][6] for single sign-on (SSO) authentication using the OpenID Connect 1.0 protocol (OIDC) on top of the OAuth 2.0 protocol. +The Sensu OIDC provider is tested with [Okta][51] and [PingFederate][52]. + +{{% notice warning %}} +**WARNING**: Defining multiple OIDC providers can lead to inconsistent authentication behavior. +Use `sensuctl auth list` to verify that you have defined only one authentication provider of type `OIDC`. +If more than one OIDC auth provider configuration is listed, use `sensuctl auth delete $NAME` to remove the extra OIDC configurations by name. +{{% /notice %}} + +For general information about configuring authentication providers, read [Configure single sign-on (SSO) authentication][12]. + +## OIDC configuration example + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: oidc +api_version: authentication/v2 +metadata: + name: oidc_name +spec: + additional_scopes: + - groups + - email + client_id: a8e43af034e7f2608780 + client_secret: b63968394be6ed2edb61c93847ee792f31bf6216 + disable_offline_access: false + redirect_uri: http://127.0.0.1:8080/api/enterprise/authentication/v2/oidc/callback + server: https://oidc.example.com:9031 + groups_claim: groups + groups_prefix: 'oidc:' + username_claim: email + username_prefix: 'oidc:' +{{< /code >}} + +{{< code json >}} +{ + "type": "oidc", + "api_version": "authentication/v2", + "metadata": { + "name": "oidc_name" + }, + "spec": { + "additional_scopes": [ + "groups", + "email" + ], + "client_id": "a8e43af034e7f2608780", + "client_secret": "b63968394be6ed2edb61c93847ee792f31bf6216", + "disable_offline_access": false, + "redirect_uri": "http://sensu-backend.example.com:8080/api/enterprise/authentication/v2/oidc/callback", + "server": "https://oidc.example.com:9031", + "groups_claim": "groups", + "groups_prefix": "oidc:", + "username_claim": "email", + "username_prefix": "oidc:" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## OIDC specification + +### OIDC top-level attributes + +type | +-------------|------ +description | Top-level attribute that specifies the [`sensuctl create`][38] resource type. For OIDC configuration, the `type` should always be `oidc`. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +type: oidc +{{< /code >}} +{{< code json >}} +{ + "type": "oidc" +} +{{< /code >}} +{{< /language-toggle >}} + +api_version | +-------------|------ +description | Top-level attribute that specifies the Sensu API group and version. For OIDC configuration, the `api_version` should always be `authentication/v2`. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +api_version: authentication/v2 +{{< /code >}} +{{< code json >}} +{ + "api_version": "authentication/v2" +} +{{< /code >}} +{{< /language-toggle >}} + +metadata | +-------------|------ +description | Top-level collection of metadata about the OIDC configuration. The `metadata` map is always at the top level of the OIDC definition. This means that in `wrapped-json` and `yaml` formats, the `metadata` scope occurs outside the `spec` scope. +required | true +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +metadata: + name: oidc_name +{{< /code >}} +{{< code json >}} +{ + "metadata": { + "name": "oidc_name" + } +} +{{< /code >}} +{{< /language-toggle >}} + +spec | +-------------|------ +description | Top-level map that includes the OIDC [spec attributes][25]. +required | true +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +spec: + additional_scopes: + - groups + - email + client_id: a8e43af034e7f2608780 + client_secret: b63968394be6ed2edb61c93847ee792f31bf6216 + disable_offline_access: false + redirect_uri: http://sensu-backend.example.com:8080/api/enterprise/authentication/v2/oidc/callback + server: https://oidc.example.com:9031 + groups_claim: groups + groups_prefix: 'oidc:' + username_claim: email + username_prefix: 'oidc:' +{{< /code >}} +{{< code json >}} +{ + "spec": { + "additional_scopes": [ + "groups", + "email" + ], + "client_id": "a8e43af034e7f2608780", + "client_secret": "b63968394be6ed2edb61c93847ee792f31bf6216", + "disable_offline_access": false, + "redirect_uri": "http://sensu-backend.example.com:8080/api/enterprise/authentication/v2/oidc/callback", + "server": "https://oidc.example.com:9031", + "groups_claim": "groups", + "groups_prefix": "oidc:", + "username_claim": "email", + "username_prefix": "oidc:" + } +} +{{< /code >}} +{{< /language-toggle >}} + +#### OIDC metadata attribute + +| name | | +-------------|------ +description | A unique string used to identify the OIDC configuration. The name cannot contain special characters or spaces (validated with Go regex [`\A[\w\.\-]+\z`][42]).

    The name you choose will be used in the web UI message for OIDC sign-in: `SIGN-IN WITH `. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +name: oidc_provider +{{< /code >}} +{{< code json >}} +{ + "name": "oidc_provider" +} +{{< /code >}} +{{< /language-toggle >}} + +#### OIDC spec attributes + +| additional_scopes | | +-------------|------ +description | Scopes to include in the claims, in addition to the default `openid` scope. {{% notice note %}} +**NOTE**: For most providers, you'll want to include `groups`, `email` and `username` in this list. +{{% /notice %}} +required | false +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +additional_scopes: +- groups +- email +- username +{{< /code >}} +{{< code json >}} +{ + "additional_scopes": [ + "groups", + "email", + "username" + ] +} +{{< /code >}} +{{< /language-toggle >}} + +| client_id | | +-------------|------ +description | The OIDC provider application client ID. {{% notice note %}} +**NOTE**: Register an application in the OIDC provider to generate a client ID. Read [register an Okta application](#register-an-okta-application) for an example. +{{% /notice %}} +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +client_id: 1c9ae3e6f3cc79c9f1786fcb22692d1f +{{< /code >}} +{{< code json >}} +{ + "client_id": "1c9ae3e6f3cc79c9f1786fcb22692d1f" +} +{{< /code >}} +{{< /language-toggle >}} + +| client_secret | | +-------------|------ +description | The OIDC provider application client secret. {{% notice note %}} +**NOTE**: Register an application in the OIDC provider to generate a client ID. Read [register an Okta application](#register-an-okta-application) for an example. +{{% /notice %}} +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +client_secret: a0f2a3c1dcd5b1cac71bf0c03f2ff1bd +{{< /code >}} +{{< code json >}} +{ + "client_secret": "a0f2a3c1dcd5b1cac71bf0c03f2ff1bd" +} +{{< /code >}} +{{< /language-toggle >}} + +| disable_offline_access | | +-------------|------ +description | If `true`, the OIDC provider cannot include the `offline_access` scope in the authentication request. Otherwise, `false`.

    We recommend setting `disable_offline_access` to `false`. If set to `true`, OIDC providers cannot return a refresh token that allows users to refresh their access tokens, and users will be logged out after 5 minutes. +required | true +default | false +type | Boolean +example | {{< language-toggle >}} +{{< code yml >}} +disable_offline_access: false +{{< /code >}} +{{< code json >}} +{ + "disable_offline_access": false +} +{{< /code >}} +{{< /language-toggle >}} + + + +| redirect_uri | | +-------------|------ +description | Redirect URL to provide to the OIDC provider. Requires `/api/enterprise/authentication/v2/oidc/callback`. {{% notice note %}} +**NOTE**: Only required for certain OIDC providers, such as Okta. +{{% /notice %}} +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +redirect_uri: http://sensu-backend.example.com:8080/api/enterprise/authentication/v2/oidc/callback +{{< /code >}} +{{< code json >}} +{ + "redirect_uri": "http://sensu-backend.example.com:8080/api/enterprise/authentication/v2/oidc/callback" +} +{{< /code >}} +{{< /language-toggle >}} + +| server | | +-------------|------ +description | The location of the OIDC server you wish to authenticate against. {{% notice note %}} +**NOTE**: If you configure with http, the connection will be insecure. +{{% /notice %}} +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +server: https://sensu.oidc.provider.example.com +{{< /code >}} +{{< code json >}} +{ + "server": "https://sensu.oidc.provider.example.com" +} +{{< /code >}} +{{< /language-toggle >}} + + + +| groups_claim | | +-------------|------ +description | The claim to use to form the associated RBAC groups. {{% notice note %}} +**NOTE**: The value held by the claim must be an array of strings. +{{% /notice %}} +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +groups_claim: groups +{{< /code >}} +{{< code json >}} +{ + "groups_claim": "groups" +} +{{< /code >}} +{{< /language-toggle >}} + +| groups_prefix | | +-------------|------ +description | The prefix added to all OIDC groups. Sensu appends the groups_prefix with a colon. For example, for the groups_prefix `okta` and the group `dev`, the resulting group name in Sensu is `okta:dev`. Use the groups_prefix when integrating OIDC groups with Sensu RBAC [role bindings and cluster role bindings][13]. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +groups_prefix: 'okta:' +{{< /code >}} +{{< code json >}} +{ + "groups_prefix": "okta:" +} +{{< /code >}} +{{< /language-toggle >}} + +| username_claim | | +-------------|------ +description | The claim to use to form the final RBAC user name. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +username_claim: email +{{< /code >}} +{{< code json >}} +{ + "username_claim": "email" +} +{{< /code >}} +{{< /language-toggle >}} + +| username_prefix | | +-------------|------ +description | The prefix added to all OIDC usernames. Sensu appends the username_prefix with a colon. For example, for the username_prefix `okta` and the user `alice`, the resulting username in Sensu is `okta:alice`. Use the username_prefix when integrating OIDC users with Sensu RBAC [role bindings and cluster role bindings][13]. Users _do not_ need to provide the username_prefix when logging in to Sensu. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +username_prefix: 'okta:' +{{< /code >}} +{{< code json >}} +{ + "username_prefix": "okta:" +} +{{< /code >}} +{{< /language-toggle >}} + +## Refresh tokens + +No matter which OIDC provider you use, make sure to enable refresh tokens during provider configuration. +If you do not enable refresh tokens in your provider configuration, Sensu will log out of the web UI, the API, and sensuctl after 5 minutes. + +## Register an Okta application + +To use Okta for authentication, register Sensu Go as an OIDC web application. +Before you start, install Sensu Go with a valid commercial license and make sure you have access to the Okta Administrator Dashboard. + +Follow the steps in this section to create an Okta application and configure an Okta OIDC provider in Sensu. + +### Create an Okta application + +{{% notice note %}} +**NOTE**: These instructions are based on the Okta Developer Console. +The steps may be different if you are using the Okta Classic UI. +{{% /notice %}} + +1. In the Okta Admin Console, navigate to *Applications*: click `Applications` > `Applications`. +2. Click **Create App Integration**. +3. In the *Create a new app integration* modal window: + - Select the sign-in method `OIDC - OpenID Connect`. + - Select the application type `Web Application`. +4. Click **Next**. +5. In the *New Web App Integration* dialog: + - In the *App integration name* field, enter the app name. +You can also upload a logo if desired. + - Under *Grant type*, click to select `Refresh Token` in the *Client acting on behalf of a user* list. + - In the *Sign-in redirect URIs* field, enter `/api/enterprise/authentication/v2/oidc/callback`. + Replace `` with your API URL, including the API [port][5] 8080. + - Under *Assignments*, click to select `Skip group assignment for now`. +6. Click **Save**. +7. Select the *Sign On* tab, scroll to the *OpenID Connect ID Token* section, and click **Edit**. +8. In the *Groups claim filter* section: + - In the first field, enter `groups` + - In the dropdown menu, select `Matches regex` + - In the second field, enter `.*` +9. Click **Save**. +10. Select the *Assignments* tab and assign people and groups to your app. + +### Configure an Okta OIDC provider + +To create your `okta` OIDC provider in Sensu: + +1. For the `additional_scopes` configuration attribute, include `groups` and `email`. + +2. For the `client_id` and `client_secret` values, use the *Client ID* and *Client secret*, respectively, listed under *General > Client Credentials* for your Okta application. + +3. For the `redirect_uri` attribute, use the *Sign-in redirect URIs* value you entered in step 5 of [Create an Okta application][50]. + +4. For the `server` value, use the *Okta domain* listed under *General > General Settings* in your Okta application. + +5. Set the `disable_offline_access` attribute to your desired value (we recommend `false`). + +6. Add your Okta groups to the `groups_claim` string. +For example, if you have an Okta group `groups` and you set the `groups_prefix` to `okta:`, you can set up RBAC objects to mention group `okta:groups` as needed. + +7. Set the `username_claim` value to `email`. + +8. Specify `groups_prefix` and `username_prefix` values if desired. + +Your Okta OIDC provider configuration should be similar to this example: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: oidc +api_version: authentication/v2 +metadata: + name: okta +spec: + additional_scopes: + - groups + - email + client_id: 4sd5jxiwxfvg82PoZ5d7 + client_secret: r78316494besnNCmtmEBnS47ee792f31bf6216 + redirect_uri: http://127.0.0.1:8080/api/enterprise/authentication/v2/oidc/callback + server: https://dev-459543913.okta.com + disable_offline_access: false + groups_claim: groups + username_claim: email + groups_prefix: 'oidc:' + username_prefix: 'oidc:' +{{< /code >}} + +{{< code json >}} +{ + "type": "oidc", + "api_version": "authentication/v2", + "metadata": { + "name": "okta" + }, + "spec": { + "additional_scopes": [ + "groups", + "email" + ], + "client_id": "4sd5jxiwxfvg82PoZ5d7", + "client_secret": "r78316494besnNCmtmEBnS47ee792f31bf6216", + "redirect_uri": "http://127.0.0.1:8080/api/enterprise/authentication/v2/oidc/callback", + "server": "https://dev-459543913.okta.com", + "disable_offline_access": false, + "groups_claim": "groups", + "username_claim": "email", + "groups_prefix": "oidc:", + "username_prefix": "oidc:" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Configure authorization for OIDC users + +Configure [authorization][3] via role-based access control (RBAC) for your OIDC users and groups by creating [roles (or cluster roles)][4] and [role bindings (or cluster role bindings)][13] that map to the user and group names. + + {{% notice note %}} +**NOTE**: If you do not configure authorization, users will be able to log in with OIDC but will have no permissions by default. +{{% /notice %}} + +## Use sensuctl to login with OIDC + +1. Run `sensuctl login oidc`. + + {{% notice note %}} +**NOTE**: You can also use [`sensuctl configure`](../../../sensuctl/#first-time-setup-and-authentication) and choose the OIDC authentication method to log in to sensuctl with OIDC. +{{% /notice %}} + +2. If you are using a desktop, a browser will open to allow you to authenticate and log in. +If a browser does not open, launch a browser to complete the login via your OIDC provider at: + + `https://:8080/api/enterprise/authentication/v2/oidc/authorize` + +## OIDC troubleshooting + +This section lists common OIDC errors and describes possible solutions for each of them. + +To troubleshoot any issue with OIDC authentication, start by [increasing the log verbosity][3] of sensu-backend to the [debug log level][5]. +Most authentication and authorization errors are only displayed on the debug log level to avoid flooding the log files. + +{{% notice note %}} +**NOTE**: If you can't locate any log entries referencing OIDC authentication, run [sensuctl auth list](../sso/#manage-authentication-providers) to make sure that you successfully installed the OIDC provider. +{{% /notice %}} + +For provider-specific troubleshooting, read the [Okta][14] or [PingFederate][15] documentation. + +### `bad request` + +After configuring OIDC access, if you receive a `bad request` error when you open the web UI, you may be using an incorrect port in the redirect URI. + +Make sure the redirect URI uses the API port, `8080`. +Confirm that the redirect URI specified in your OIDC provider as well as in the [`redirect_uri` attribute][9] in your Sensu OIDC definition both use port `8080`. +For example, the URL `http://127.0.0.1:8080/api/enterprise/authentication/v2/oidc/callback` uses the correct port. + +### `could not find the groups claim in the user's claims` + +If you see the following error when you open the web UI, the [`groups_claim`][10] value in your Sensu OIDC definition is incorrect: + +{{< code text >}} +{"message":"could not find the groups claim \"okta:groups\" in the user's claims: [\"sub\" \"email\" \"email_verified\"]","code":0} +{{< /code >}} + +Update your OIDC definition to specify `groups` as the value for the [`groups_claim` attribute][10]. + +### No namespaces or resources in the web UI after OIDC sign-in + +You must configure [RBAC authorization][3] for your OIDC users and groups by creating [roles (or cluster roles)][4] and [role bindings (or cluster role bindings)][13] that map to the user and group names. + +If you do not configure authorization, users will be able to log in with OIDC but will have no permissions, so they will not see any namespaces or resources in the web UI. + +### Inconsistent authentication + +If you experience inconsistent authentication with OIDC sign-in, such as being unable to sign in after previously signing in successfully, you may have configured more than one OIDC authentication provider. + +Run [sensuctl auth list](../sso/#manage-authentication-providers) to make sure that you have only one authentication provider listed for type `OIDC`. +If more than one OIDC authentication provider is listed, use `sensuctl auth delete $NAME` to remove the extra OIDC configuration by name. + + +[1]: ../../../web-ui/ +[2]: ../../../sensuctl/ +[3]: ../#authorization +[4]: ../rbac/#roles-and-cluster-roles +[5]: ../../deploy-sensu/install-sensu/#ports +[6]: ../../../commercial/ +[7]: ../#use-built-in-basic-authentication +[8]: ../../../api/ +[9]: #redirect-uri-attribute +[10]: #groups-claim-attribute +[12]: ../sso/ +[13]: ../rbac#role-bindings-and-cluster-role-bindings +[14]: https://help.okta.com/oag/en-us/Content/Topics/Access-Gateway/trouble-shooting-guide.htm +[15]: https://docs.pingidentity.com/bundle/pingfederate-110/page/age1564003028292.html +[17]: ../rbac#namespaced-resource-types +[18]: ../rbac#cluster-wide-resource-types +[19]: ../../maintain-sensu/troubleshoot#log-levels +[25]: #oidc-spec-attributes +[36]: ../../../sensuctl/#first-time-setup-and-authentication +[38]: ../../../sensuctl/create-manage-resources/#create-resources +[41]: https://en.wikipedia.org/wiki/Fully_qualified_domain_name +[42]: https://regex101.com/r/zo9mQU/2 +[50]: #create-an-okta-application +[51]: https://www.okta.com/ +[52]: https://www.pingidentity.com/en/software/pingfederate.html +[53]: ../../../api/core/users/ +[54]: https://etcd.io/ diff --git a/content/sensu-go/6.12/operations/control-access/rbac.md b/content/sensu-go/6.12/operations/control-access/rbac.md new file mode 100644 index 0000000000..3e43665e41 --- /dev/null +++ b/content/sensu-go/6.12/operations/control-access/rbac.md @@ -0,0 +1,3316 @@ +--- +title: "Role-based access control (RBAC) reference" +linkTitle: "RBAC Reference" +reference_title: "Role-based access control (RBAC)" +type: "reference" +description: "Read this reference to learn how Sensu's role-based access control helps teams and projects share a Sensu instance, authorize access, and grant permissions." +weight: 80 +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: control-access +--- + +Sensu's role-based access control (RBAC) helps different teams and projects share a Sensu instance. +Use RBAC to specify the actions users are allowed to take against specific Sensu resources, within [namespaces][12] or across all namespaces, based on roles bound to the user or to one or more groups the user is a member of. + +- [Roles][53] create sets of permissions (for example, get and delete) tied to resource types. +[Cluster roles][13] apply permissions across namespaces and include access to [cluster-wide resources][18] like users and namespaces. +- [Users][56] represent a person or agent that interacts with Sensu. +Users can belong to one or more [groups][57]. +- [Role bindings][55] assign a role to a set of users and groups within a namespace. +[Cluster role bindings][23] assign a cluster role to a set of users and groups cluster-wide. + +RBAC configuration applies to [sensuctl][2], the [API][19], and the [web UI][3]. + +## Resources + +Permissions within Sensu can be scoped to resource types, like checks, handlers, and users. +List resource types in the [rules][58] arrays of role and cluster role definitions to configure permissions. + +### Namespaced resource types + +Namespaced resources belong to a single [namespace][12]. +You can set permissions for namespaced resources with [roles][53] and [cluster roles][13]. + +| Resource type | Description | +|---|---| +| `assets` | [Dynamic runtime asset][5] resources within a namespace | +| `checks` | [Check][6] resources within a namespace | +| `entities` | [Entity][7] resources within a namespace | +| `events` | [Event][8] resources within a namespace | +| `extensions` | Placeholder type +| `filters` | [Filter][22] resources within a namespace | +| `handlers` | [Handler][9] resources within a namespace | +| `hooks` | [Hook][10] resources within a namespace | +| `mutators` | [Mutator][11] resources within a namespace | +| `pipelines` | Resources composed of [event processing workflows][52] | +| `rolebindings` | Namespace-specific role assigners | +| `roles` | Namespace-specific permission sets | +| `rule-templates` | [Resources applied to service components][38] for business service monitoring | +| `searches` | Saved [web UI][49] search queries | +| `secrets` |[Secrets][48] (for example, username or password) | +| `service-components` | Resources that represent [elements in a business service][36] | +| `silenced` | [Silencing][14] resources within a namespace | +| `sumo-logic-metrics-handlers` | Persistent handlers for [transmitting metrics to Sumo Logic][43] | +| `tcp-stream-handlers` | Persistent handlers for [sending events to TCP sockets][44] for remote storage | + +### Cluster-wide resource types + +Cluster-wide resources cannot be assigned to a namespace. +You can set permissions for cluster-wide resources only with [cluster roles][13]. + +| Resource type | Description | +|---|---| +| `apikeys` | [Persistent universally unique identifier (UUID)][33] for authentication | +| `authproviders` | [Authentication provider][32] configuration | +| `clusterrolebindings` | Cluster-wide role assigners | +| `clusterroles` | Cluster-wide permission sets | +| `clusters` | Sensu clusters running multiple [Sensu backends][1] | +| `config` | Global configuration for [web UI display][21] | +| `etcd-replicators` | [Mirror RBAC resource changes][40] to follower clusters | +| `license` | Sensu [commercial license][37] | +| `namespaces` | Resource partitions within a Sensu instance | +| `provider` | [PostgreSQL event store][47] provider | +| `providers` | [Secrets providers][46] | +| `users` | People or agents that interact with Sensu | + +### Special resource types + +You can set permissions for special resource types with [roles][53] and [cluster roles][13]. + +| Type | Description | +|---|---| +| `*` | All resources within Sensu. **The `*` type takes precedence over other rules within the same role.** If you want to deny a certain type, you can't use the `*` type. Instead, you must explicitly allow every type required. When applied to a role, the `*` type applies only to [namespaced resource types][17]. When applied to a cluster role, the `*` type applies to both [namespaced resource types][17] and [cluster-wide resource types][18]. | + +## Users + +A user represents a person or an agent that interacts with Sensu. + +You can assign users to one or more [roles][53] or [cluster roles][13]. +You can also assign users to one or more [groups][57]. +Users inherit all permissions from each role or cluster role they are assigned to, whether they are assigned as users or as a member of a group. + +Users can use their assigned Sensu username and password to [configure sensuctl][26] and log in to the [web UI][3]. + +### User example + +The following example shows a user resource definition: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: User +api_version: core/v2 +metadata: {} +spec: + disabled: false + groups: + - ops + - dev + password: user_password + password_hash: $5f$14$.brXRviMZpbaleSq9kjoUuwm67V/s4IziOLGHjEqxJbzPsreQAyNm + username: alice +{{< /code >}} + +{{< code json >}} +{ + "type": "User", + "api_version": "core/v2", + "metadata": {}, + "spec": { + "username": "alice", + "password": "user_password", + "password_hash": "$5f$14$.brXRviMZpbaleSq9kjoUuwm67V/s4IziOLGHjEqxJbzPsreQAyNm", + "disabled": false, + "groups": ["ops", "dev"] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +To create this user with [`sensuctl create`][31], first, save the definition to a file like `users.yml` or `users.json`. +Then, run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl create --file users.yml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl create --file users.json +{{< /code >}} + +{{< /language-toggle >}} + +### Default users + +Sensu automatically creates an administrator user and an `agent` user during installation. + +#### Administrator user + +During the [Sensu backend installation][42] process, you create a username and password for an `admin` user. + +The `admin` user is automatically added to the `cluster-admins` group and the `cluster-admin` cluster role, which are both listed in the cluster role binding `cluster-admin`. +The group, cluster role, and cluster role binding assignments give the `admin` user permissions to manage all aspects of Sensu, as well as create new users. + +After you [configure sensuctl][26], you can [change the `admin` user's password][45] with the `change-password` command. + +#### `agent` user + +Sensu creates a default `agent` user with the password `P@ssw0rd!` during startup. +The user/password combination corresponds to the defaults the Sensu agent uses. + +By default, the `agent` user belongs to the `system:agent` group. +The `system:agent` cluster role binding grants the `system:agent` cluster role to the members of this group. +To grant agent users the permissions they need to report events into any namespace, add agent users to the `system:agent` group. + +Configure the `agent` user's credentials with the [`user`][41] and [`password`][68] agent configuration options. + +### View users + +Use [sensuctl][2] to list all users within Sensu. + +To return a list of users in `yaml` or `wrapped-json` format for use with `sensuctl create`: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl user list --format yaml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl user list --format wrapped-json +{{< /code >}} + +{{< /language-toggle >}} + +### Test and change user passwords + +To test the password for a user created with Sensu's [built-in basic authentication][34], run: + +{{< code shell >}} +sensuctl user test-creds --password '' +{{< /code >}} + +An empty response indicates the user's password is valid. +A `request-unauthorized` response indicates the user's password is invalid. + +{{% notice note %}} +**NOTE**: The `sensuctl user test-creds` command tests passwords for users created with Sensu's built-in [basic authentication](../#use-built-in-basic-authentication). +It does not test user credentials defined via an authentication provider like [Lightweight Directory Access Protocol (LDAP)](../ldap-auth/), [Active Directory (AD)](../ad-auth/), or [OpenID Connect 1.0 protocol (OIDC)](../oidc-auth/). +{{% /notice %}} + +To change a user's password: + +{{< code shell >}} +sensuctl user change-password --current-password --new-password +{{< /code >}} + +You can also use sensuctl to [reset a user's password][50] or [generate a password hash][51]. + +### Create users + +You can use [sensuctl][2] to create users. +For example, the following command creates a user with the username `alice`, creates a password, and assigns the user to the `ops` and `dev` groups: + +{{< code shell >}} +sensuctl user create alice --password='' --groups=ops,dev +{{< /code >}} + +{{% notice note %}} +**NOTE**: Passwords must have at least eight characters. +{{% /notice %}} + +You can create any number of users, each with their own passwords. +As a general rule, users have no permissions by default. +Users are granted permissions by role bindings or cluster role bindings. + +### Disable users + +To disable a user, run: + +{{< code shell >}} +sensuctl user disable +{{< /code >}} + +To reinstate a disabled user, run: + +{{< code shell >}} +sensuctl user reinstate +{{< /code >}} + +### Assign user permissions + +To assign permissions to a user: + +1. [Create the user][27]. +2. [Create a role][25] (or a [cluster role][28] for cluster-wide access). +3. [Create a role binding][25] (or [cluster role binding][28]) to assign the role to the user. + +## Groups + +A group is a set of users within Sensu. +You can assign groups to one or more roles, and users can belong to one or more groups. + +Groups inherit all permissions from each role they are assigned to. + +{{% notice note %}} +**NOTE**: Groups are not a resource type within Sensu. +Instead, groups are created and managed only within user definitions. +{{% /notice %}} + +### Default groups + +Sensu includes a default `cluster-admins` group that contains the [default `admin` user][20] and a `system:agents` group used internally by Sensu agents. + +### Add groups to users + +Use [sensuctl][2] to add a group to a user: + +{{< code shell >}} +sensuctl user add-group +{{< /code >}} + +You can also set a user's list of groups to a specific list: + +{{< code shell >}} +sensuctl user set-groups [,, ...] +{{< /code >}} + +### Remove groups from users + +Use [sensuctl][2] to remove groups from users. + +To remove a group from a user: + +{{< code shell >}} +sensuctl user remove-group +{{< /code >}} + +To remove all groups from a user: + +{{< code shell >}} +sensuctl user remove-groups +{{< /code >}} + +## Roles + +A role is a set of permissions that control access to Sensu resources within a single namespace. +Use [role bindings][55] to assign roles to users and groups. + +To create and manage roles within a single namespace, [create a role][25] with `roles` permissions within that namespace. +To create and manage roles cluster-wide, [configure sensuctl][26] as the [default `admin` user][20] or [create a cluster role][28] with `roles` permissions. + +To avoid recreating commonly used roles in every namespace, [create a cluster role][28] and use a [role binding][25] (not a cluster role binding) to restrict permissions within a specific namespace. + +### Role example + +The following example shows a role resource definition: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Role +api_version: core/v2 +metadata: + name: namespaced-resources-all-verbs +spec: + rules: + - resources: + - assets + - checks + - entities + - events + - filters + - handlers + - hooks + - mutators + - pipelines + - rolebindings + - roles + - silenced + - sumo-logic-metrics-handlers + - tcp-stream-handlers + verbs: + - get + - list + - create + - update + - delete +{{< /code >}} + +{{< code json >}} +{ + "type": "Role", + "api_version": "core/v2", + "metadata": { + "name": "namespaced-resources-all-verbs" + }, + "spec": { + "rules": [ + { + "resources": [ + "assets", + "checks", + "entities", + "events", + "filters", + "handlers", + "hooks", + "mutators", + "pipelines", + "rolebindings", + "roles", + "silenced", + "sumo-logic-metrics-handlers", + "tcp-stream-handlers" + ], + "verbs": [ + "get", + "list", + "create", + "update", + "delete" + ] + } + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +To create this role with [`sensuctl create`][31], first save the definition to a file like `roles.yml` or `roles.json`. + +Then, run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl create --file roles.yml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl create --file roles.json +{{< /code >}} + +{{< /language-toggle >}} + +### Default roles + +Every [Sensu backend][1] includes the `system:pipeline` role, which is a facility that allows the EventFilter engine to load events from Sensu's event store. +The `system:pipeline` role is an implementation detail and should not be assigned to Sensu users. + +### View roles + +Use [sensuctl][2] to list all roles within Sensu: + +{{< code shell >}} +sensuctl role list +{{< /code >}} + +To review the permissions and scope for a specific role: + +{{< code shell >}} +sensuctl role info admin +{{< /code >}} + +To get help managing roles with sensuctl: + +{{< code shell >}} +sensuctl role help +{{< /code >}} + +### Edit roles + +To edit a role: + +{{< code shell >}} +sensuctl edit role +{{< /code >}} + +To get more information about available flags, run: + +{{< code shell >}} +sensuctl edit --help +{{< /code >}} + +### Create roles + +You can use [sensuctl][2] to create roles. +Read [Create a role and role binding][25] for an example. + +### Delete roles + +To delete a role: + +{{< code shell >}} +sensuctl role delete +{{< /code >}} + +## Cluster roles + +A cluster role is a set of permissions that control access to Sensu resources. +Cluster roles can include permissions for [cluster-wide resources][18] in addition to [namespaced resources][17]. + +You can also use cluster roles (in conjunction with [cluster role bindings][23]) to grant access to namespaced resources across all namespaces. +This allows you to run commmands like `sensuctl check list --all-namespaces`. + +To create and manage cluster roles, [configure sensuctl][26] as the [default `admin` user][20] or [create a cluster role][28] with permissions for `clusterroles`. +To create and manage roles cluster-wide, [configure sensuctl][26] as the [default `admin` user][20] or create a cluster role with `roles` permissions. + +To avoid recreating commonly used roles in every namespace, [create a cluster role][28] and use a [role binding][25] (not a cluster role binding) to restrict permissions within a specific namespace. + +### Cluster role example + +The following example shows a cluster role resource definition: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: ClusterRole +api_version: core/v2 +metadata: + name: all-resources-all-verbs +spec: + rules: + - resources: + - assets + - checks + - entities + - events + - filters + - handlers + - hooks + - mutators + - pipelines + - rolebindings + - roles + - silenced + - cluster + - clusterrolebindings + - clusterroles + - namespaces + - users + - authproviders + - license + - sumo-logic-metrics-handlers + - tcp-stream-handlers + verbs: + - get + - list + - create + - update + - delete +{{< /code >}} + +{{< code json >}} +{ + "type": "ClusterRole", + "api_version": "core/v2", + "metadata": { + "name": "all-resources-all-verbs" + }, + "spec": { + "rules": [ + { + "resources": [ + "assets", + "checks", + "entities", + "events", + "filters", + "handlers", + "hooks", + "mutators", + "pipelines", + "rolebindings", + "roles", + "silenced", + "cluster", + "clusterrolebindings", + "clusterroles", + "namespaces", + "users", + "authproviders", + "license", + "sumo-logic-metrics-handlers", + "tcp-stream-handlers" + ], + "verbs": [ + "get", + "list", + "create", + "update", + "delete" + ] + } + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +To create this cluster role with [`sensuctl create`][31], first save the definition to a file like `cluster_roles.yml` or `cluster_roles.json`. +Then, run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl create --file cluster_roles.yml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl create --file cluster_roles.json +{{< /code >}} + +{{< /language-toggle >}} + +### Default cluster roles + +Every [Sensu backend][1] includes the following cluster roles: + +| Cluster role name | Description | +| ----------------- | ----------- | +| `cluster-admin` | Full access to all [resource types][4] across namespaces, including access to [cluster-wide resource types][18]. | +| `admin` | Full access to all [resource types][4]. Apply this cluster role within a namespace with a [role binding][55] (not a cluster role binding). | +| `edit` | Read and write access to most [resource types][4] except roles and role bindings. Apply this cluster role within a namespace with a [role binding][55] (not a cluster role binding). | +| `view` | Read-only access to most [resource types][4] except roles and role bindings. Apply this cluster role within a namespace with a [role binding][55] (not a cluster role binding). | +| `system:agent` | Used internally by Sensu agents. Configure an agent's user credentials with the [`user` and `password` agent configuration flags][41]. | +| `system:user` | Get and update permissions for local resources for the current user. | + +### View cluster roles + +Use [sensuctl][2] to list all cluster roles within Sensu: + +{{< code shell >}} +sensuctl cluster-role list +{{< /code >}} + +To review the permissions and scope for a specific cluster role: + +{{< code shell >}} +sensuctl cluster-role info +{{< /code >}} + +To get help managing roles with sensuctl: + +{{< code shell >}} +sensuctl cluster-role help +{{< /code >}} + +### Create cluster roles + +You can use [sensuctl][2] to create cluster roles. +Read [Create a cluster role and cluster role binding][28] for an example. + +### Delete cluster roles + +To delete a cluster role: + +{{< code shell >}} +sensuctl cluster-role delete +{{< /code >}} + +## Role bindings + +A role binding assigns a role or a cluster role to users and groups within a single namespace. + +To create and manage role bindings within a namespace, [create a role][25] with `rolebindings` permissions within that namespace, and log in by [configuring sensuctl][26]. + +Without an assigned role or cluster role, users can sign in to the web UI but can't access any Sensu resources. +With the correct roles and bindings configured, users can log in to [sensuctl][2] and the [web UI][3] using their single-sign-on username and password (no prefixes required). + +Make sure to include the groups_prefix and username_prefix for the authentication provider when you create Sensu role bindings. + +### Role binding example + +The following example shows a role binding resource definition: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: RoleBinding +api_version: core/v2 +metadata: + name: event-reader-binding +spec: + role_ref: + name: event-reader + type: Role + subjects: + - name: bob + type: User +{{< /code >}} + +{{< code json >}} +{ + "type": "RoleBinding", + "api_version": "core/v2", + "metadata": { + "name": "event-reader-binding" + }, + "spec": { + "role_ref": { + "name": "event-reader", + "type": "Role" + }, + "subjects": [ + { + "name": "bob", + "type": "User" + } + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +To create this role binding with [`sensuctl create`][31], first save the definition to a file like `rolebindings.yml` or `rolebindings.json`. +Then, run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl create --file rolebindings.yml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl create --file rolebindings.json +{{< /code >}} + +{{< /language-toggle >}} + +### Default role bindings + +Every [Sensu backend][1] includes the `system:pipeline` role binding, a facility that allows the EventFilter engine to load events from Sensu's event store. +The `system:pipeline` role binding is an implementation detail and should not be applied to Sensu users. | + +#### View role bindings + +Use [sensuctl][2] to list all role bindings within Sensu: + +{{< code shell >}} +sensuctl role-binding list +{{< /code >}} + +To review the details for a specific role binding: + +{{< code shell >}} +sensuctl role-binding info +{{< /code >}} + +To get help managing role bindings with sensuctl: + +{{< code shell >}} +sensuctl role-binding help +{{< /code >}} + +### Create role bindings + +You can use [sensuctl][2] to create role bindings that assign a role to users and groups. +Read [Create a role and role binding][25] for an example. + +### Delete role bindings + +To delete a role binding: + +{{< code shell >}} +sensuctl role-binding delete +{{< /code >}} + +## Cluster role bindings + +A cluster role binding assigns a cluster role to users and groups across namespaces and resource types. + +To create and manage cluster role bindings, [configure sensuctl][26] as the [default `admin` user][20] or [create a cluster role][28] with permissions for `clusterrolebindings`. + +Without an assigned role or cluster role, users can sign in to the web UI but can't access any Sensu resources. +With the correct roles and bindings configured, users can log in to [sensuctl][2] and the [web UI][3] using their single-sign-on username and password (no prefixes required). + +Make sure to include the groups_prefix and username_prefix for the authentication provider when creating Sensu cluster role bindings. + +### Cluster role binding example + +The following example shows a cluster role binding resource definition: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: ClusterRoleBinding +api_version: core/v2 +metadata: + name: cluster-admin +spec: + role_ref: + name: cluster-admin + type: ClusterRole + subjects: + - name: Cluster_Admins + type: Group +{{< /code >}} + +{{< code json >}} +{ + "type": "ClusterRoleBinding", + "api_version": "core/v2", + "metadata": { + "name": "cluster-admin" + }, + "spec": { + "role_ref": { + "name": "cluster-admin", + "type": "ClusterRole" + }, + "subjects": [ + { + "name": "Cluster_Admins", + "type": "Group" + } + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +{{% notice note %}} +**NOTE**: If you are using Active Directory (AD) or Lightweight Directory Access Protocol (LDAP) authentication, the names of users and groups listed in the subjects array must exactly match the user and group names the authentication provider returns to the Sensu backend. +{{% /notice %}} + +To create this cluster role binding with [`sensuctl create`][31], first save the definition to a file like `clusterrolebindings.yml` or `clusterrolebindings.json`. +Then, run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl create --file clusterrolebindings.yml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl create --file clusterrolebindings.json +{{< /code >}} + +{{< /language-toggle >}} + +### Default cluster role bindings + +Every [Sensu backend][1] includes the following cluster role bindings: + +| Cluster role binding name | Description | +| --------------- | ----------- | +| `cluster-admin` | `ClusterRoleBinding` | Full access to all [resource types][4] across namespaces, including access to [cluster-wide resource types][18]. | +| `system:agent` | `ClusterRoleBinding` | Full access to all events. Used internally by Sensu agents. | +| `system:user` | `ClusterRoleBinding` | Get and update access for local resources for the current user. | + +### View cluster role bindings + +Use [sensuctl][2] to list all cluster role bindings within Sensu: + +{{< code shell >}} +sensuctl cluster-role-binding list +{{< /code >}} + +To review the details for a specific role binding: + +{{< code shell >}} +sensuctl cluster-role-binding info +{{< /code >}} + +To get help managing cluster role bindings with sensuctl: + +{{< code shell >}} +sensuctl cluster-role-binding help +{{< /code >}} + +### Create cluster role bindings + +You can use [sensuctl][2] to create cluster role bindings that assign cluster roles to users and groups. +Read [Create a cluster role and cluster role binding][28] for an example. + +### Delete cluster role bindings + +To delete a role binding: + +{{< code shell >}} +sensuctl cluster-role-binding delete +{{< /code >}} + +## Create a role and role binding + +This example will create a role and a role binding that assigns the role to a group. +As a result, all users who are assigned the group will have get, list, create, update, and delete permissions for all resources in the production namespace. + +The following command creates a `prod-admin` role restricted to the production namespace: + +{{< code shell >}} +sensuctl role create prod-admin --verb='get,list,create,update,delete' --resource='*' --namespace production +{{< /code >}} + +The command creates the following role resource definition: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Role +api_version: core/v2 +metadata: + name: prod-admin + namespace: production +spec: + rules: + - resources: + - '*' + verbs: + - get + - list + - create + - update + - delete +{{< /code >}} + +{{< code json >}} +{ + "type": "Role", + "api_version": "core/v2", + "metadata": { + "name": "prod-admin", + "namespace": "production" + }, + "spec": { + "rules": [ + { + "resources": [ + "*" + ], + "verbs": [ + "get", + "list", + "create", + "update", + "delete" + ] + } + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +Run the following command to create a role binding (or [cluster role binding][23]) to assign the `prod-admin` role created above to a group named `oncall`: + +{{< code shell >}} +sensuctl role-binding create prod-admin-oncall --role=prod-admin --group=oncall +{{< /code >}} + +This command creates the following role binding resource definition: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: RoleBinding +api_version: core/v2 +metadata: + name: prod-admin-oncall +spec: + role_ref: + name: prod-admin + type: Role + subjects: + - name: oncall + type: Group +{{< /code >}} + +{{< code json >}} +{ + "type": "RoleBinding", + "api_version": "core/v2", + "metadata": { + "name": "prod-admin-oncall" + }, + "spec": { + "role_ref": { + "name": "prod-admin", + "type": "Role" + }, + "subjects": [ + { + "name": "oncall", + "type": "Group" + } + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +Role bindings can also assign cluster roles to users and groups within a single namespace. +For example, to create a role binding that assigns the `global-event-reader` cluster role to the user `angela` and the `event-readers` group, run: + +{{< code shell >}} +sensuctl role-binding create event-readers-binding --cluster-role=global-event-reader --user=angela --group=read-events-only +{{< /code >}} + +This command creates a role binding resource definition similar to the following: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: RoleBinding +api_version: core/v2 +metadata: + name: event-readers-binding + namespace: default +spec: + role_ref: + name: global-event-reader + type: ClusterRole + subjects: + - name: read-events-only + type: Group + - name: angela + type: User +{{< /code >}} + +{{< code json >}} +{ + "type": "RoleBinding", + "api_version": "core/v2", + "metadata": { + "name": "event-readers-binding", + "namespace": "default" + }, + "spec": { + "role_ref": { + "name": "global-event-reader", + "type": "ClusterRole" + }, + "subjects": [ + { + "name": "read-events-only", + "type": "Group" + }, + { + "name": "angela", + "type": "User" + } + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Create a role and role binding with a group prefix + +In this example, if a groups_prefix of `ad` is configured for [Active Directory authentication][39], the role and role binding will give a `dev` group access to create and manage Sensu workflows within the `default` namespace: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Role +api_version: core/v2 +metadata: + name: workflow-creator +spec: + rules: + - resources: + - checks + - hooks + - filters + - events + - filters + - mutators + - pipelines + - handlers + - sumo-logic-metrics-handlers + - tcp-stream-handlers + verbs: + - get + - list + - create + - update + - delete +{{< /code >}} + +{{< code json >}} +{ + "type": "Role", + "api_version": "core/v2", + "metadata": { + "name": "workflow-creator" + }, + "spec": { + "rules": [ + { + "resources": [ + "checks", + "hooks", + "filters", + "events", + "filters", + "mutators", + "pipelines", + "handlers", + "sumo-logic-metrics-handlers", + "tcp-stream-handlers" + ], + "verbs": [ + "get", + "list", + "create", + "update", + "delete" + ] + } + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: RoleBinding +api_version: core/v2 +metadata: + name: dev-binding-with-groups-prefix +spec: + role_ref: + name: workflow-creator + type: Role + subjects: + - name: ad:dev + type: Group +{{< /code >}} + +{{< code json >}} +{ + "type": "RoleBinding", + "api_version": "core/v2", + "metadata": { + "name": "dev-binding-with-groups-prefix" + }, + "spec": { + "role_ref": { + "name": "workflow-creator", + "type": "Role" + }, + "subjects": [ + { + "name": "ad:dev", + "type": "Group" + } + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Create a cluster role and cluster role binding + +This example will create a cluster role and a cluster role role binding that assigns the cluster role to a user and a group. +As a result, the individual user and all users who are assigned the group will have read-only access to events (and only events) across all namespaces in Sensu. + +For example, the following command creates a `global-event-reader` cluster role that can read events in all namespaces: + +{{< code shell >}} +sensuctl cluster-role create global-event-reader --verb='get,list' --resource='events' +{{< /code >}} + +The command creates the following cluster role resource definition: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: ClusterRole +api_version: core/v2 +metadata: + name: global-event-reader +spec: + rules: + - resources: + - events + verbs: + - get + - list +{{< /code >}} + +{{< code json >}} +{ + "type": "ClusterRole", + "api_version": "core/v2", + "metadata": { + "name": "global-event-reader" + }, + "spec": { + "rules": [ + { + "resources": [ + "events" + ], + "verbs": [ + "get", + "list" + ] + } + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +Next, run the following command to assign the `global-event-reader` cluster role to the user `angela` and the group `global-event-readers`: + +{{< code shell >}} +sensuctl cluster-role-binding create global-event-reader-binding --cluster-role=global-event-reader --user=angela --group=global-event-readers +{{< /code >}} + +This command creates a cluster role binding resource definition similar to the following: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: ClusterRoleBinding +api_version: core/v2 +metadata: + name: global-event-reader-binding +spec: + role_ref: + name: global-event-reader + type: ClusterRole + subjects: + - name: global-event-readers + type: Group + - name: angela + type: User +{{< /code >}} + +{{< code json >}} +{ + "type": "ClusterRoleBinding", + "api_version": "core/v2", + "metadata": { + "name": "global-event-reader-binding" + }, + "spec": { + "role_ref": { + "name": "global-event-reader", + "type": "ClusterRole" + }, + "subjects": [ + { + "name": "global-event-readers", + "type": "Group" + }, + { + "name": "angela", + "type": "User" + } + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Assign user permissions within a namespace + +To assign permissions to a user: + +1. [Create the user][27]. +2. [Create a role][25]. +3. [Create a role binding][25] to assign the role to the user. + +For example, the following configuration creates a user `alice`, a role `default-admin`, and a role binding `alice-default-admin`, giving `alice` full permissions for [namespaced resource types][17] within the `default` namespace. +You can add these resources to Sensu using [`sensuctl create`][31]. + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: User +api_version: core/v2 +metadata: {} +spec: + disabled: false + username: alice + password: user_password +{{< /code >}} + +{{< code json >}} +{ + "type": "User", + "api_version": "core/v2", + "metadata": {}, + "spec": { + "disabled": false, + "username": "alice", + "password": "user_password" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Role +api_version: core/v2 +metadata: + name: default-admin +spec: + rules: + - resources: + - assets + - checks + - entities + - events + - filters + - handlers + - hooks + - mutators + - pipelines + - rolebindings + - roles + - searches + - silenced + - sumo-logic-metrics-handlers + - tcp-stream-handlers + verbs: + - get + - list + - create + - update + - delete +{{< /code >}} + +{{< code json >}} +{ + "type": "Role", + "api_version": "core/v2", + "metadata": { + "name": "default-admin" + }, + "spec": { + "rules": [ + { + "resources": [ + "assets", + "checks", + "entities", + "events", + "filters", + "handlers", + "hooks", + "mutators", + "pipelines", + "rolebindings", + "roles", + "searches", + "silenced", + "sumo-logic-metrics-handlers", + "tcp-stream-handlers" + ], + "verbs": [ + "get", + "list", + "create", + "update", + "delete" + ] + } + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: RoleBinding +api_version: core/v2 +metadata: + name: alice-default-admin +spec: + role_ref: + name: default-admin + type: Role + subjects: + - name: alice + type: User +{{< /code >}} + +{{< code json >}} +{ + "type": "RoleBinding", + "api_version": "core/v2", + "metadata": { + "name": "alice-default-admin" + }, + "spec": { + "role_ref": { + "name": "default-admin", + "type": "Role" + }, + "subjects": [ + { + "name": "alice", + "type": "User" + } + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Assign group permissions within a namespace + +To assign permissions to group of users: + +1. [Create at least one user assigned to a group][27]. +2. [Create a role][25]. +3. [Create a role binding][25] to assign the role to the group. + +For example, the following configuration creates a user `alice` assigned to the group `ops`, a role `default-admin`, and a role binding `ops-default-admin`, giving the `ops` group full permissions for [namespaced resource types][17] within the `default` namespace. +You can add these resources to Sensu using [`sensuctl create`][31]. + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: User +api_version: core/v2 +metadata: {} +spec: + disabled: false + username: alice + password: user_password + groups: + - ops +{{< /code >}} + +{{< code json >}} +{ + "type": "User", + "api_version": "core/v2", + "metadata": {}, + "spec": { + "disabled": false, + "username": "alice", + "password": "user_password", + "groups": [ + "ops" + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Role +api_version: core/v2 +metadata: + name: default-admin +spec: + rules: + - resources: + - assets + - checks + - entities + - events + - filters + - handlers + - hooks + - mutators + - pipelines + - rolebindings + - roles + - searches + - silenced + - sumo-logic-metrics-handlers + - tcp-stream-handlers + verbs: + - get + - list + - create + - update + - delete +{{< /code >}} + +{{< code json >}} +{ + "type": "Role", + "api_version": "core/v2", + "metadata": { + "name": "default-admin" + }, + "spec": { + "rules": [ + { + "resources": [ + "assets", + "checks", + "entities", + "events", + "filters", + "handlers", + "hooks", + "mutators", + "pipelines", + "rolebindings", + "roles", + "searches", + "silenced", + "sumo-logic-metrics-handlers", + "tcp-stream-handlers" + ], + "verbs": [ + "get", + "list", + "create", + "update", + "delete" + ] + } + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: RoleBinding +api_version: core/v2 +metadata: + name: ops-default-admin +spec: + role_ref: + name: default-admin + type: Role + subjects: + - name: ops + type: Group +{{< /code >}} + +{{< code json >}} +{ + "type": "RoleBinding", + "api_version": "core/v2", + "metadata": { + "name": "ops-default-admin" + }, + "spec": { + "role_ref": { + "name": "default-admin", + "type": "Role" + }, + "subjects": [ + { + "name": "ops", + "type": "Group" + } + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +{{% notice protip %}} +**PRO TIP**: To avoid recreating commonly used roles in each namespace, [create a cluster role](#create-a-cluster-role-and-cluster-role-binding) and use a [role binding](#role-bindings) to restrict permissions within a specific namespace. +{{% /notice %}} + +## Assign group permissions across all namespaces + +To assign cluster-wide permissions to group of users: + +1. [Create at least one user assigned to a group][27]. +2. [Create a cluster role][28]. +3. [Create a cluster role binding][28] to assign the role to the group. + +For example, the following configuration creates a user `alice` assigned to the group `ops`, a cluster role `default-admin`, and a cluster role binding `ops-default-admin`, giving the `ops` group full permissions for [namespaced resource types][17] and [cluster-wide resource types][18] across all namespaces. +You can add these resources to Sensu using [`sensuctl create`][31]. + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: User +api_version: core/v2 +metadata: {} +spec: + disabled: false + username: alice + password: user_password + groups: + - ops +{{< /code >}} + +{{< code json >}} +{ + "type": "User", + "api_version": "core/v2", + "metadata": {}, + "spec": { + "disabled": false, + "username": "alice", + "password": "user_password", + "groups": [ + "ops" + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: ClusterRole +api_version: core/v2 +metadata: + name: default-admin +spec: + rules: + - resources: + - assets + - checks + - entities + - events + - filters + - handlers + - hooks + - mutators + - pipelines + - rolebindings + - roles + - silenced + - cluster + - clusterrolebindings + - clusterroles + - namespaces + - users + - authproviders + - license + - sumo-logic-metrics-handlers + - tcp-stream-handlers + verbs: + - get + - list + - create + - update + - delete +{{< /code >}} + +{{< code json >}} +{ + "type": "ClusterRole", + "api_version": "core/v2", + "metadata": { + "name": "default-admin" + }, + "spec": { + "rules": [ + { + "resources": [ + "assets", + "checks", + "entities", + "events", + "filters", + "handlers", + "hooks", + "mutators", + "pipelines", + "rolebindings", + "roles", + "silenced", + "cluster", + "clusterrolebindings", + "clusterroles", + "namespaces", + "users", + "authproviders", + "license", + "sumo-logic-metrics-handlers", + "tpc-stream-handlers" + ], + "verbs": [ + "get", + "list", + "create", + "update", + "delete" + ] + } + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: ClusterRoleBinding +api_version: core/v2 +metadata: + name: ops-default-admin +spec: + role_ref: + name: default-admin + type: ClusterRole + subjects: + - name: ops + type: Group +{{< /code >}} + +{{< code json >}} +{ + "type": "ClusterRoleBinding", + "api_version": "core/v2", + "metadata": { + "name": "ops-default-admin" + }, + "spec": { + "role_ref": { + "name": "default-admin", + "type": "ClusterRole" + }, + "subjects": [ + { + "name": "ops", + "type": "Group" + } + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Assign different permissions for different resource types + +You can assign different permissions for different resource types in a role or cluster role definition. +To do this, you'll still create at least one user assigned to a group, a role or cluster role, and a role binding or cluster role binding. +However, in this case, the role or cluster role will include more than one rule. + +For example, you may want users in a testing group to be able to get and list all resource types but create, update, and delete only silenced entries across all namespaces. +Create a user `alice` assigned to the group `ops_testing`, a cluster role `manage_silences` with two rules (one for all resources and one just for silences), and a cluster role binding `ops_testing_manage_silences`: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: User +api_version: core/v2 +metadata: {} +spec: + disabled: false + username: alice + password: user_password + groups: + - ops_testing +{{< /code >}} + +{{< code json >}} +{ + "type": "User", + "api_version": "core/v2", + "metadata": {}, + "spec": { + "disabled": false, + "username": "alice", + "password": "user_password", + "groups": [ + "ops_testing" + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: ClusterRole +api_version: core/v2 +metadata: + name: manage_silences +spec: + rules: + - verbs: + - get + - list + resources: + - '*' + - verbs: + - create + - update + - delete + resources: + - silenced +{{< /code >}} + +{{< code json >}} +{ + "type": "ClusterRole", + "api_version": "core/v2", + "metadata": { + "name": "manage_silences" + }, + "spec": { + "rules": [ + { + "verbs": [ + "get", + "list" + ], + "resources": [ + "*" + ] + }, + { + "verbs": [ + "create", + "update", + "delete" + ], + "resources": [ + "silenced" + ] + } + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: ClusterRoleBinding +api_version: core/v2 +metadata: + name: ops_testing_manage_silences +spec: + role_ref: + name: manage_silences + type: ClusterRole + subjects: + - name: ops_testing + type: Group +{{< /code >}} + +{{< code json >}} +{ + "type": "ClusterRoleBinding", + "api_version": "core/v2", + "metadata": { + "name": "ops_testing_manage_silences" + }, + "spec": { + "role_ref": { + "name": "manage_silences", + "type": "ClusterRole" + }, + "subjects": [ + { + "name": "ops_testing", + "type": "Group" + } + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +Create as many rules as you need in the role or cluster role. +For example, you can configure a role or cluster role that includes one rule for each verb, with each rule listing only the resources that verb should apply to. + +Here's another example that includes three rules. +Each rule specifies different access permissions for the resource types listed in the rule. +In addition, the user group would have no access at all for the two resources that are not listed: API keys and licences. + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: User +api_version: core/v2 +metadata: {} +spec: + disabled: false + username: alice + password: user_password + groups: + - ops +{{< /code >}} + +{{< code json >}} +{ + "type": "User", + "api_version": "core/v2", + "metadata": {}, + "spec": { + "disabled": false, + "username": "alice", + "password": "user_password", + "groups": [ + "ops" + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: ClusterRole +api_version: core/v2 +metadata: + name: ops_access +spec: + rules: + - verbs: + - get + - list + resources: + - entities + - events + - rolebindings + - roles + - clusterrolebindings + - clusterroles + - config + - users + - verbs: + - get + - list + - create + - update + - delete + resources: + - assets + - checks + - filters + - handlers + - hooks + - mutators + - pipelines + - rule-templates + - searches + - secrets + - service-components + - silenced + - sumo-logic-metrics-handlers + - tcp-stream-handlers + - clusters + - etcd-replicators + - providers + - verbs: + - get + - list + - create + - update + resources: + - authproviders + - namespaces + - provider +{{< /code >}} + +{{< code json >}} +{ + "type": "ClusterRole", + "api_version": "core/v2", + "metadata": { + "name": "ops_access" + }, + "spec": { + "rules": [ + { + "verbs": [ + "get", + "list" + ], + "resources": [ + "entities", + "events", + "rolebindings", + "roles", + "clusterrolebindings", + "clusterroles", + "config", + "users" + ] + }, + { + "verbs": [ + "get", + "list", + "create", + "update", + "delete" + ], + "resources": [ + "assets", + "checks", + "filters", + "handlers", + "hooks", + "mutators", + "pipelines", + "rule-templates", + "searches", + "secrets", + "service-components", + "silenced", + "sumo-logic-metrics-handlers", + "tcp-stream-handlers", + "clusters", + "etcd-replicators", + "providers" + ] + }, + { + "verbs": [ + "get", + "list", + "create", + "update" + ], + "resources": [ + "authproviders", + "namespaces", + "provider" + ] + } + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: ClusterRoleBinding +api_version: core/v2 +metadata: + name: ops_access_assignment +spec: + role_ref: + name: ops_access + type: ClusterRole + subjects: + - name: ops + type: Group +{{< /code >}} + +{{< code json >}} +{ + "type": "ClusterRoleBinding", + "api_version": "core/v2", + "metadata": { + "name": "ops_access_assignment" + }, + "spec": { + "role_ref": { + "name": "ops_access", + "type": "ClusterRole" + }, + "subjects": [ + { + "name": "ops", + "type": "Group" + } + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Reuse cluster roles across namespaces + +Reusing cluster roles across namespaces can reduce the number of resources you need to manage. + +For example, suppose you have three teams, each with its own namespace. +You write a script that uses [limited service accounts][15] to create and delete silences. +You want to use the script for all three team namespaces, so you create a role with the required permissions and a role binding in each namespace: six new resources. +If you need to change the permissions for the script, you will need to update each role in the team namespaces (three resources). + +A better approach is to create a single cluster role that grants the required permissions, plus one role binding in each namespace to tie the permissions to the namespace's limited service account. +With this configuration, you only need to update one resource to make permission changes: the `silencing-script` cluster role. +Sensu will automatically apply updates in each team's namespace using the role bindings that define each limited service account as a subject of the cluster role. + +1. Create a [limited service account][15] user in each namespace: + + {{< code shell >}} +sensuctl user create silencing-service-team-1 --password='password' +{{< /code >}} + + This creates the following user definition: + + {{< language-toggle >}} +{{< code yml >}} +--- +type: User +api_version: core/v2 +metadata: + name: silencing-service-team-1 +spec: + disabled: false + username: silencing-service-team-1 +{{< /code >}} +{{< code json >}} +{ + "type": "User", + "api_version": "core/v2", + "metadata": { + "name": "silencing-service-team-1" + }, + "spec": { + "disabled": false, + "username": "silencing-service-team-1" + } +} +{{< /code >}} +{{< /language-toggle >}} + + Repeat this step to create a limited service account user in each team's namespace. + +2. Create a [cluster role][28] with get, list, create, update, and delete permissions for silences: + + {{< code shell >}} +sensuctl cluster-role create silencing-script --verb get,list,create,update,delete --resource silenced +{{< /code >}} + + This command creates the cluster role that has the permissions the silencing service accounts will need: + + {{< language-toggle >}} +{{< code yml >}} +--- +type: ClusterRole +api_version: core/v2 +metadata: + name: silencing-script +spec: + rules: + - resources: + - silenced + verbs: + - get + - list + - create + - update + - delete +{{< /code >}} +{{< code json >}} +{ + "type": "ClusterRole", + "api_version": "core/v2", + "metadata": { + "name": "silencing-script" + }, + "spec": { + "rules": [ + { + "resources": [ + "silenced" + ], + "verbs": [ + "get", + "list", + "create", + "update", + "delete" + ] + } + ] + } +} +{{< /code >}} +{{< /language-toggle >}} + +3. Create a [role binding][25] in each team namespace to assign the `silencing-script` cluster role to the team's `silencing-service` user. +For example, use this command to create the role binding for Team 1: + + {{< code shell >}} +sensuctl role-binding create silencing-script-binding-team-1 --cluster-role silencing-script --user silencing-service-team-1 --namespace team1 +{{< /code >}} + + This command creates the role binding that ties the correct permissions (via the `silencing-script` cluster role) with your service account (via the user `silencing-service-team-1`): + {{< language-toggle >}} +{{< code yml >}} +--- +type: RoleBinding +api_version: core/v2 +metadata: + name: silencing-script-binding-team-1 +spec: + role_ref: + name: silencing-script + type: ClusterRole + subjects: + - name: silencing-service-team-1 + type: User +{{< /code >}} +{{< code json >}} +{ + "type": "RoleBinding", + "api_version": "core/v2", + "metadata": { + "name": "silencing-script-binding-team-1" + }, + "spec": { + "role_ref": { + "name": "silencing-script", + "type": "ClusterRole" + }, + "subjects": [ + { + "name": "silencing-service-team-1", + "type": "User" + } + ] + } +} +{{< /code >}} +{{< /language-toggle >}} + + Repeat this step to create a role binding for the `silencing-script` cluster role and the limited service account user in each team's namespace. + +## User specification + +### Top-level attributes for user resources + +api_version | +-------------|------ +description | Top-level attribute that specifies the Sensu API group and version. For users in this version of Sensu, this attribute should always be `core/v2`. +required | Required for user definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][31]. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +api_version: core/v2 +{{< /code >}} +{{< code json >}} +{ + "api_version": "core/v2" +} +{{< /code >}} +{{< /language-toggle >}} + +metadata | +-------------|------ +description | Top-level collection of metadata about the user, including `name`. The `metadata` map is always at the top level of the user definition. This means that in `wrapped-json` and `yaml` formats, the `metadata` scope occurs outside the `spec` scope. Read [metadata attributes for user resources][59] for details. +required | Required for user definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][31]. +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +metadata: + name: alice +{{< /code >}} +{{< code json >}} +{ + "metadata": { + "name": "alice" + } +} +{{< /code >}} +{{< /language-toggle >}} + +spec | +-------------|------ +description | Top-level map that includes the [user spec attributes][60]. +required | Required for user definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][31]. +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +spec: + disabled: false + groups: + - ops + - dev + password: user_password + password_hash: $5f$14$.brXRviMZpbaleSq9kjoUuwm67V/s4IziOLGHjEqxJbzPsreQAyNm + username: alice +{{< /code >}} +{{< code json >}} +{ + "spec": { + "disabled": false, + "groups": [ + "ops", + "dev" + ], + "password": "user_password", + "password_hash": "$5f$14$.brXRviMZpbaleSq9kjoUuwm67V/s4IziOLGHjEqxJbzPsreQAyNm", + "username": "alice" + } +} +{{< /code >}} +{{< /language-toggle >}} + +type | +-------------|------ +description | Top-level attribute that specifies the [`sensuctl create`][31] resource type. Users should always be type `User`. +required | Required for user definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][31]. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +type: User +{{< /code >}} +{{< code json >}} +{ + "type": "User" +} +{{< /code >}} +{{< /language-toggle >}} + +### Metadata attributes for user resources + +| name | | +-------------|------ +description | Unique string used to identify the user. User resource names cannot contain special characters or spaces (validated with Go regex [`\A[\w\.\-]+\z`][54]). Each user resource must have a unique name. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +name: alice +{{< /code >}} +{{< code json >}} +{ + "name": "alice" +} +{{< /code >}} +{{< /language-toggle >}} + +### Spec attributes for user resources + +disabled | +-------------|------ +description | If `true`, the user's account is disabled. Otherwise, `false`. +required | false +type | Boolean +default | `false` +example | {{< language-toggle >}} +{{< code yml >}} +disabled: false +{{< /code >}} +{{< code json >}} +{ + "disabled": false +} +{{< /code >}} +{{< /language-toggle >}} + +groups | +-------------|------ +description | Groups to which the user belongs. +required | false +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +groups: +- dev +- ops +{{< /code >}} +{{< code json >}} +{ + "groups": [ + "dev", + "ops" + ] +} +{{< /code >}} +{{< /language-toggle >}} + + + +password | +-------------|------ +description | User's password. Passwords must have at least eight characters.{{% notice note %}} +**NOTE**: You only need to set either the `password` or the [`password_hash`](#password-hash-attribute) (not both). We recommend using the `password_hash` because it eliminates the need to store cleartext passwords. +{{% /notice %}} +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +password: user_password +{{< /code >}} +{{< code json >}} +{ + "password": "user_password" +} +{{< /code >}} +{{< /language-toggle >}} + + + +password_hash | +--------------|------ +description | [Bcrypt][35] password hash. You can use the `password_hash` in your user definitions instead of storing cleartext passwords. {{% notice note %}} +**NOTE**: You only need to set either the [`password`](#password-attribute) or the `password_hash` (not both). We recommend using the `password_hash` because it eliminates the need to store cleartext passwords. +{{% /notice %}} +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +password_hash: $5f$14$.brXRviMZpbaleSq9kjoUuwm67V/s4IziOLGHjEqxJbzPsreQAyNm +{{< /code >}} +{{< code json >}} +{ + "password_hash": "$5f$14$.brXRviMZpbaleSq9kjoUuwm67V/s4IziOLGHjEqxJbzPsreQAyNm" +} +{{< /code >}} +{{< /language-toggle >}} + +username | +-------------|------ +description | Name of the user. Cannot contain special characters. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +username: alice +{{< /code >}} +{{< code json >}} +{ + "username": "alice" +} +{{< /code >}} +{{< /language-toggle >}} + +## Role and cluster role specification + +### Top-level attributes for role and cluster role resources + +api_version | +-------------|------ +description | Top-level attribute that specifies the Sensu API group and version. For role and cluster role resources in this version of Sensu, this attribute should always be `core/v2`. +required | Required for role and cluster role definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][31]. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +api_version: core/v2 +{{< /code >}} +{{< code json >}} +{ + "api_version": "core/v2" +} +{{< /code >}} +{{< /language-toggle >}} + +metadata | +-------------|------ +description | Top-level collection of metadata about the role or cluster role. The `metadata` map is always at the top level of the role or cluster role definition. This means that in `wrapped-json` and `yaml` formats, the `metadata` scope occurs outside the `spec` scope. Read [metadata attributes for role and cluster role resources][61] for details.{{% notice note %}} +**NOTE**: Cluster role definitions do not include a `namespace` attribute in the resource metadata. +{{% /notice %}} +required | Required for role definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][31]. +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +metadata: + annotations: + managed-by: prod-admin + created_by: admin + labels: + environment: prod1 + region: us-west-1 + sensu.io/managed_by: sensuctl + name: prod-user + namespace: production +{{< /code >}} +{{< code json >}} +{ + "metadata": { + "annotations": { + "managed-by": "prod-admin" + }, + "created_by": "admin", + "labels": { + "environment": "prod1", + "region": "us-west-1", + "sensu.io/managed_by": "sensuctl" + }, + "name": "prod-user", + "namespace": "production" + } +} +{{< /code >}} +{{< /language-toggle >}} + +spec | +-------------|------ +description | Top-level map that includes the [role or cluster role spec attributes][62]. +required | Required for role or cluster role definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][31]. +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +spec: + rules: + - resource_names: null + resources: + - checks + - entities + - events + - filters + - handlers + - hooks + - mutators + - pipelines + - searches + - service-components + - silenced + - sumo-logic-metrics-handlers + - tcp-stream-handlers + verbs: + - get + - list + - create + - update + - delete +{{< /code >}} +{{< code json >}} +{ + "spec": { + "rules": [ + { + "resource_names": null, + "resources": [ + "checks", + "entities", + "events", + "filters", + "handlers", + "hooks", + "mutators", + "pipelines", + "searches", + "service-components", + "silenced", + "sumo-logic-metrics-handlers", + "tcp-stream-handlers" + ], + "verbs": [ + "get", + "list", + "create", + "update", + "delete" + ] + } + ] + } +} +{{< /code >}} +{{< /language-toggle >}} + +type | +-------------|------ +description | Top-level attribute that specifies the [`sensuctl create`][31] resource type. Roles should always be type `Role`. Cluster roles should always be type `ClusterRole`. +required | Required for role and cluster role definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][31]. +type | String +example (role) | {{< language-toggle >}} +{{< code yml >}} +type: Role +{{< /code >}} +{{< code json >}} +{ + "type": "Role" +} +{{< /code >}} +{{< /language-toggle >}} +example
    (cluster role) | {{< language-toggle >}} +{{< code yml >}} +type: ClusterRole +{{< /code >}} +{{< code json >}} +{ + "type": "ClusterRole" +} +{{< /code >}} +{{< /language-toggle >}} + +### Metadata attributes for role and cluster role resources + +| annotations | | +-------------|------ +description | Non-identifying metadata to include with observation event data that you can access with [event filters][22]. You can use annotations to add data that's meaningful to people or external tools that interact with Sensu.

    In contrast to labels, you cannot use annotations in [API response filtering][19], [sensuctl response filtering][2], or [web UI views][3]. +required | false +type | Map of key-value pairs. Keys and values can be any valid UTF-8 string. +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +annotations: + managed-by: prod-admin +{{< /code >}} +{{< code json >}} +{ + "annotations": { + "managed-by": "prod-admin" + } +} +{{< /code >}} +{{< /language-toggle >}} + +| created_by | | +-------------|------ +description | Username of the Sensu user who created or last updated the role or cluster role. Sensu automatically populates the `created_by` field when the role or cluster role is created or updated. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +created_by: admin +{{< /code >}} +{{< code json >}} +{ + "created_by": "admin" +} +{{< /code >}} +{{< /language-toggle >}} + +| labels | | +-------------|------ +description | Custom attributes to include with observation event data that you can use for response and web UI view filtering.

    If you include labels in your event data, you can filter [API responses][19], [sensuctl responses][2], and [web UI views][3] based on them. In other words, labels allow you to create meaningful groupings for your data.

    Limit labels to metadata you need to use for response filtering. For complex, non-identifying metadata that you will *not* need to use in response filtering, use annotations rather than labels. +required | false +type | Map of key-value pairs. Keys can contain only letters, numbers, and underscores and must start with a letter. Values can be any valid UTF-8 string. +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +labels: + environment: prod1 + region: us-west-1 + sensu.io/managed_by: sensuctl +{{< /code >}} +{{< code json >}} +{ + "labels": { + "environment": "prod1", + "region": "us-west-1", + "sensu.io/managed_by": "sensuctl" + } +} +{{< /code >}} +{{< /language-toggle >}} + +| name | | +-------------|------ +description | Unique string used to identify the role or cluster role. Role and cluster role names cannot contain special characters or spaces (validated with Go regex [`\A[\w\.\-]+\z`][54]). Each role must have a unique name within its namespace. Each cluster role must have a unique name. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +name: prod-user +{{< /code >}} +{{< code json >}} +{ + "name": "prod-user" +} +{{< /code >}} +{{< /language-toggle >}} + +| namespace | | +-------------|------ +description | [Sensu RBAC namespace][26] that the role belongs to.{{% notice note %}} +**NOTE**: Cluster role definitions do not include a `namespace` attribute in the resource metadata. +{{% /notice %}} +required | false +type | String +default | `default` +example | {{< language-toggle >}} +{{< code yml >}} +namespace: production +{{< /code >}} +{{< code json >}} +{ + "namespace": "production" +} +{{< /code >}} +{{< /language-toggle >}} + +### Spec attributes for role and cluster role resources + +rules | +-------------|------ +description | Rule set that the role or cluster role applies. A rule is an explicit statement that grants a particular access to a resource. Read [rules attributes][58] for more information. +required | true +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +rules: +- resource_names: + - check-cpu + resources: + - checks + - entities + - events + - filters + - handlers + - hooks + - mutators + - pipelines + - searches + - service-components + - silenced + - sumo-logic-metrics-handlers + - tcp-stream-handlers + verbs: + - get + - list + - create + - update + - delete +{{< /code >}} +{{< code json >}} +{ + "rules": [ + { + "resource_names": [ + "check-cpu" + ], + "resources": [ + "checks", + "entities", + "events", + "filters", + "handlers", + "hooks", + "mutators", + "pipelines", + "searches", + "service-components", + "silenced", + "sumo-logic-metrics-handlers", + "tcp-stream-handlers" + ], + "verbs": [ + "get", + "list", + "create", + "update", + "delete" + ] + } + ] +} +{{< /code >}} +{{< /language-toggle >}} + +#### Rules attributes + +resources | +-------------|------ +description | Types of resources that the rule has permission to access. Read [resource types][4] to learn more about available types. +required | true +type | Array +allowed values (roles) | [Namespaced resource types][17] and the [special resource type `*`][64]. +allowed values (cluster roles) | [Namespaced resource types][17], [cluster-wide resource types][18], and the [special resource type `*`][64]. +example | {{< language-toggle >}} +{{< code yml >}} +resources: +- checks +- entities +- events +- filters +- handlers +- hooks +- mutators +- pipelines +- searches +- service-components +- silenced +- sumo-logic-metrics-handlers +- tcp-stream-handlers +{{< /code >}} +{{< code json >}} +{ + "resources": [ + "checks", + "entities", + "events", + "filters", + "handlers", + "hooks", + "mutators", + "pipelines", + "searches", + "service-components", + "silenced", + "sumo-logic-metrics-handlers", + "tcp-stream-handlers" + ] +} +{{< /code >}} +{{< /language-toggle >}} + +resource_names | +-------------|------ +description | Names of specific individual resources that the rule has permission to access. Resource name permissions are only taken into account for requests that use `get`, `update`, and `delete` verbs. +required | false +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +resource_names: +- check-cpu +{{< /code >}} +{{< code json >}} +{ + "resource_names": [ + "check-cpu" + ] +} +{{< /code >}} +{{< /language-toggle >}} + +verbs | +-------------|------ +description | Type of access the rule will apply. +required | true +type | Array +allowed values | `get`, `list`, `create`, `update`, `delete` +example | {{< language-toggle >}} +{{< code yml >}} +verbs: +- get +- list +- create +- update +- delete +{{< /code >}} +{{< code json >}} +{ + "verbs": [ + "get", + "list", + "create", + "update", + "delete" + ] +} +{{< /code >}} +{{< /language-toggle >}} + +## Role binding and cluster role binding specification + +### Top-level attributes for role binding and cluster role binding resources + +api_version | +-------------|------ +description | Top-level attribute that specifies the Sensu API group and version. For role binding and cluster role binding resources in this version of Sensu, this attribute should always be `core/v2`. +required | Required for role binding and cluster role binding definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][31]. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +api_version: core/v2 +{{< /code >}} +{{< code json >}} +{ + "api_version": "core/v2" +} +{{< /code >}} +{{< /language-toggle >}} + +metadata | +-------------|------ +description | Top-level collection of metadata about the role binding or cluster role binding. The `metadata` map is always at the top level of the role binding or cluster role binding definition. This means that in `wrapped-json` and `yaml` formats, the `metadata` scope occurs outside the `spec` scope. Read [metadata attributes for role binding and cluster role binding resources][63] for details.{{% notice note %}} +**NOTE**: Cluster role binding definitions do not include a `namespace` attribute in the resource metadata. +{{% /notice %}} +required | Required for role binding and cluster role binding definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][31]. +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +metadata: + annotations: + managed-by: prod-admin + created_by: admin + labels: + environment: prod1 + region: us-west-1 + sensu.io/managed_by: sensuctl + name: prod-user + namespace: production +{{< /code >}} +{{< code json >}} +{ + "metadata": { + "annotations": { + "managed-by": "prod-admin" + }, + "created_by": "admin", + "labels": { + "environment": "prod1", + "region": "us-west-1", + "sensu.io/managed_by": "sensuctl" + }, + "name": "prod-user", + "namespace": "production" + } +} +{{< /code >}} +{{< /language-toggle >}} + +spec | +-------------|------ +description | Top-level map that includes the [role binding and cluster role binding spec attributes][65]. +required | Required for role binding or cluster role binding definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][31]. +type | Map of key-value pairs +example (role) | {{< language-toggle >}} +{{< code yml >}} +spec: + role_ref: + name: prod-admin + type: Role + subjects: + - name: oncall + type: Group + - name: angela + type: User +{{< /code >}} +{{< code json >}} +{ + "spec": { + "role_ref": { + "name": "prod-admin", + "type": "Role" + }, + "subjects": [ + { + "name": "oncall", + "type": "Group" + }, + { + "name": "angela", + "type": "User" + } + ] + } +} +{{< /code >}} +{{< /language-toggle >}} +example (cluster role) | {{< language-toggle >}} +{{< code yml >}} +spec: + role_ref: + name: global-event-reader + type: ClusterRole + subjects: + - name: global-event-readers + type: Group + - name: angela + type: User +{{< /code >}} +{{< code json >}} +{ + "spec": { + "role_ref": { + "name": "global-event-reader", + "type": "ClusterRole" + }, + "subjects": [ + { + "name": "global-event-readers", + "type": "Group" + }, + { + "name": "angela", + "type": "User" + } + ] + } +} +{{< /code >}} +{{< /language-toggle >}} + +type | +-------------|------ +description | Top-level attribute that specifies the [`sensuctl create`][31] resource type. Role bindings should always be type `RoleBinding`. Cluster role bindings should always be type `ClusterRoleBinding`. +required | Required for role binding and cluster role binding definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][31]. +type | String +example (role binding) | {{< language-toggle >}} +{{< code yml >}} +type: RoleBinding +{{< /code >}} +{{< code json >}} +{ + "type": "RoleBinding" +} +{{< /code >}} +{{< /language-toggle >}} +example (cluster role binding) | {{< language-toggle >}} +{{< code yml >}} +type: ClusterRoleBinding +{{< /code >}} +{{< code json >}} +{ + "type": "ClusterRoleBinding" +} +{{< /code >}} +{{< /language-toggle >}} + +### Metadata attributes for role binding and cluster role binding resources + +| annotations | | +-------------|------ +description | Non-identifying metadata to include with observation event data that you can access with [event filters][22]. You can use annotations to add data that's meaningful to people or external tools that interact with Sensu.

    In contrast to labels, you cannot use annotations in [API response filtering][19], [sensuctl response filtering][2], or [web UI views][3]. +required | false +type | Map of key-value pairs. Keys and values can be any valid UTF-8 string. +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +annotations: + managed-by: prod-admin +{{< /code >}} +{{< code json >}} +{ + "annotations": { + "managed-by": "prod-admin" + } +} +{{< /code >}} +{{< /language-toggle >}} + +| created_by | | +-------------|------ +description | Username of the Sensu user who created or last updated the role binding or cluster role binding. Sensu automatically populates the `created_by` field when the role binding or cluster role binding is created or updated. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +created_by: admin +{{< /code >}} +{{< code json >}} +{ + "created_by": "admin" +} +{{< /code >}} +{{< /language-toggle >}} + +| labels | | +-------------|------ +description | Custom attributes to include with observation event data that you can use for response and web UI view filtering.

    If you include labels in your event data, you can filter [API responses][19], [sensuctl responses][2], and [web UI views][3] based on them. In other words, labels allow you to create meaningful groupings for your data.

    Limit labels to metadata you need to use for response filtering. For complex, non-identifying metadata that you will *not* need to use in response filtering, use annotations rather than labels. +required | false +type | Map of key-value pairs. Keys can contain only letters, numbers, and underscores and must start with a letter. Values can be any valid UTF-8 string. +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +labels: + environment: prod1 + region: us-west-1 + sensu.io/managed_by: sensuctl +{{< /code >}} +{{< code json >}} +{ + "labels": { + "environment": "prod1", + "region": "us-west-1", + "sensu.io/managed_by": "sensuctl" + } +} +{{< /code >}} +{{< /language-toggle >}} + +| name | | +-------------|------ +description | Unique string used to identify the role binding or cluster role binding. Role binding and cluster role binding names cannot contain special characters or spaces (validated with Go regex [`\A[\w\.\-]+\z`][54]). Each role binding must have a unique name within its namespace. Each cluster role binding must have a unique name. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +name: prod-user +{{< /code >}} +{{< code json >}} +{ + "name": "prod-user" +} +{{< /code >}} +{{< /language-toggle >}} + +| namespace | | +-------------|------ +description | [Sensu RBAC namespace][26] that the role binding belongs to.{{% notice note %}} +**NOTE**: Cluster role binding definitions do not include a `namespace` attribute in the resource metadata. +{{% /notice %}} +required | false +type | String +default | `default` +example | {{< language-toggle >}} +{{< code yml >}} +namespace: production +{{< /code >}} +{{< code json >}} +{ + "namespace": "production" +} +{{< /code >}} +{{< /language-toggle >}} + +### Spec attributes for role binding and cluster role binding resources + +role_ref | +-------------|------ +description | Name and type for the role or cluster role to bind to the users and groups listed in the [subjects][67] array. Read [role_ref attributes][66] for more information. +required | true +type | Hash +example (role binding) | {{< language-toggle >}} +{{< code yml >}} +role_ref: + name: prod-admin + type: Role +{{< /code >}} +{{< code json >}} +{ + "role_ref": { + "name": "prod-admin", + "type": "Role" + } +} +{{< /code >}} +{{< /language-toggle >}} +example (cluster role binding) | {{< language-toggle >}} +{{< code yml >}} +role_ref: + name: global-event-reader + type: ClusterRole +{{< /code >}} +{{< code json >}} +{ + "role_ref": { + "name": "global-event-reader", + "type": "ClusterRole" + } +} +{{< /code >}} +{{< /language-toggle >}} + +subjects | +-------------|------ +description | Users and groups to bind with the role or cluster role listed in the [role_ref][66] attribute. Read [subjects attributes][67] for more information. +required | true +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +subjects: +- name: oncall + type: Group +- name: angela + type: User +{{< /code >}} +{{< code json >}} +{ + "subjects": [ + { + "name": "oncall", + "type": "Group" + }, + { + "name": "angela", + "type": "User" + } + ] +} +{{< /code >}} +{{< /language-toggle >}} + +#### `role_ref` attributes + +name | +-------------|------ +description | Name of the role or cluster role to bind in the role binding or cluster role binding. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +name: event-reader +{{< /code >}} +{{< code json >}} +{ + "name": "event-reader" +} +{{< /code >}} +{{< /language-toggle >}} + +type | +-------------|------ +description | The [sensuctl create][31] resource type for the role or cluster role. Use `Role` if you are binding a role. Use `ClusterRole` if you are binding a cluster role. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +type: Role +{{< /code >}} +{{< code json >}} +{ + "type": "Role" +} +{{< /code >}} +{{< /language-toggle >}} + +#### `subjects` attributes + +name | +-------------|------ +description | Name of the user resource or group resource to bind in the role binding or cluster role binding.{{% notice note %}}**NOTE**: If you are using Active Directory (AD) or Lightweight Directory Access Protocol (LDAP) authentication, names of users and groups are case-sensitive. The user and group names listed in the cluster role binding configuration must exactly match the user and group names the authentication provider returns to the Sensu backend. +{{% /notice %}} +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +name: alice +{{< /code >}} +{{< code json >}} +{ + "name": "alice" +} +{{< /code >}} +{{< /language-toggle >}} +example with prefix | {{< language-toggle >}} +{{< code yml >}} +name: ad:alice +{{< /code >}} +{{< code json >}} +{ + "name": "ad:alice" +} +{{< /code >}} +{{< /language-toggle >}} + +type | +-------------|------ +description | The [sensuctl create][31] resource type for the user or group to bind. Use `User` if you are binding a user. Use `Group` if you are binding a group. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +type: Group +{{< /code >}} +{{< code json >}} +{ + "type": "Group" +} +{{< /code >}} +{{< /language-toggle >}} + + +[1]: ../../../observability-pipeline/observe-schedule/backend/ +[2]: ../../../sensuctl/ +[3]: ../../../web-ui/ +[4]: #resources +[5]: ../../../plugins/assets/ +[6]: ../../../observability-pipeline/observe-schedule/checks/ +[7]: ../../../observability-pipeline/observe-entities/entities/ +[8]: ../../../observability-pipeline/observe-events/events/ +[9]: ../../../observability-pipeline/observe-process/handlers/ +[10]: ../../../observability-pipeline/observe-schedule/hooks/ +[11]: ../../../observability-pipeline/observe-transform/mutators/ +[12]: ../namespaces/ +[13]: #cluster-roles +[14]: ../../../observability-pipeline/observe-process/silencing/ +[15]: ../create-limited-service-accounts/ +[16]: ../../../reference/ +[17]: #namespaced-resource-types +[18]: #cluster-wide-resource-types +[19]: ../../../api/ +[20]: #agent-user +[21]: ../../../web-ui/webconfig-reference/ +[22]: ../../../observability-pipeline/observe-filter/filters/ +[23]: #cluster-role-bindings +[24]: #role-and-cluster-role-specification +[25]: #create-a-role-and-role-binding +[26]: ../../deploy-sensu/install-sensu/#install-sensuctl +[27]: #create-users +[28]: #create-a-cluster-role-and-cluster-role-binding +[30]: #role-binding-and-cluster-role-binding-specification +[31]: ../../../sensuctl/create-manage-resources/#create-resources +[32]: ../sso/ +[33]: ../../../api/#authenticate-with-an-api-key +[34]: ../#use-built-in-basic-authentication +[35]: https://en.wikipedia.org/wiki/Bcrypt +[36]: ../../../observability-pipeline/observe-schedule/service-components/ +[37]: ../../maintain-sensu/license/ +[38]: ../../../observability-pipeline/observe-schedule/rule-templates/ +[39]: ../ad-auth/#ad-groups-prefix +[40]: ../../deploy-sensu/etcdreplicators/ +[41]: ../../../observability-pipeline/observe-schedule/agent/#agent-password-option +[42]: ../../deploy-sensu/install-sensu/#install-the-sensu-backend +[43]: ../../../observability-pipeline/observe-process/sumo-logic-metrics-handlers/ +[44]: ../../../observability-pipeline/observe-process/tcp-stream-handlers/ +[45]: ../../../sensuctl/#change-the-admin-users-password +[46]: ../../manage-secrets/secrets-providers/ +[47]: ../../deploy-sensu/datastore/ +[48]: ../../manage-secrets/secrets/ +[49]: ../../../web-ui/search/#save-a-search +[50]: ../../../sensuctl/#reset-a-user-password +[51]: ../../../sensuctl/#generate-a-password-hash +[52]: ../../../observability-pipeline/observe-process/pipelines/ +[53]: #roles +[54]: https://regex101.com/r/zo9mQU/2 +[55]: #role-bindings +[56]: #users +[57]: #groups +[58]: #rules-attributes +[59]: #metadata-attributes-for-user-resources +[60]: #spec-attributes-for-user-resources +[61]: #metadata-attributes-for-role-and-cluster-role-resources +[62]: #spec-attributes-for-role-and-cluster-role-resources +[63]: #metadata-attributes-for-role-binding-and-cluster-role-binding-resources +[64]: #special-resource-types +[65]: #spec-attributes-for-role-binding-and-cluster-role-binding-resources +[66]: #role_ref-attributes +[67]: #subjects-attributes +[68]: ../../../observability-pipeline/observe-schedule/agent/#agent-user-option +[68]: ../../../observability-pipeline/observe-schedule/agent/#agent-user-option diff --git a/content/sensu-go/6.12/operations/control-access/sso.md b/content/sensu-go/6.12/operations/control-access/sso.md new file mode 100644 index 0000000000..d324b96fe7 --- /dev/null +++ b/content/sensu-go/6.12/operations/control-access/sso.md @@ -0,0 +1,102 @@ +--- +title: "Configure single sign-on (SSO) authentication" +linkTitle: "Configure SSO Authentication" +description: "Configure single sign-on (SSO) auth for Sensu with Lightweight Directory Access Protocol (LDAP), Active Directory (AD), or OpenID Connect 1.0 protocol (OIDC)." +weight: 10 +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: control-access +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access authentication providers for single sign-on (SSO) in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} + +Sensu requires username and password authentication to access the [web UI][1], [API][3], and [sensuctl][2] command line tool. + +In addition to the [built-in basic authentication][4], Sensu offers [commercial support][5] for using Lightweight Directory Access Protocol (LDAP), Active Directory (AD), or OpenID Connect 1.0 protocol (OIDC) for single sign-on (SSO) authentication. + +This guide describes general information for configuring an authentication provider for SSO. +Read the [LDAP][8], [AD][6], or [OIDC][7] reference documentation for provider-specific examples and specifications. + +## Configure authentication providers + +To configure an external authentication provider for SSO, first write an authentication provider configuration definition. +Follow the examples and specifications for your provider: + +- **Lightweight Directory Access Protocol (LDAP)**, including standards-compliant tools like OpenLDAP ([configuration examples][11] and [specification][13]) +- **Microsoft Active Directory (AD)**, including Azure AD ([configuration examples][14] and [specification][15]) +- **OpenID Connect 1.0 protocol (OIDC)**, including tools like Okta and PingFederate ([configuration examples][9] and [specification][12]) + +Save your configuration definition to a file, such as `authconfig.yaml` or `authconfig.json`. + +After you have a saved configuration definition, you can apply the configuration with sensuctl. +Log in to sensuctl as the [default admin user][3] and use sensuctl to apply your authentication provider configuration to Sensu: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl create --file authconfig.yml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl create --file authconfig.json +{{< /code >}} + +{{< /language-toggle >}} + +Use sensuctl to verify that your provider configuration was applied successfully: + +{{< code shell >}} +sensuctl auth list +{{< /code >}} + +The response will list your authentication provider types and names: + +{{< code text >}} + Type Name +────── ────────── + ldap openldap +{{< /code >}} + +## Manage authentication providers + +View and delete authentication providers with [enterprise/authentication/v2 API endpoints][10] or these sensuctl commands. + +To view active authentication providers: + +{{< code shell >}} +sensuctl auth list +{{< /code >}} + +To view configuration details for an authentication provider named `openldap`: + +{{< code shell >}} +sensuctl auth info openldap +{{< /code >}} + +To delete an authentication provider named `openldap`: + +{{< code shell >}} +sensuctl auth delete openldap +{{< /code >}} + + +[1]: ../../../web-ui/ +[2]: ../../../sensuctl/ +[3]: ../../../api/ +[4]: ../#use-built-in-basic-authentication +[5]: ../../../commercial/ +[6]: ../ad-auth/ +[7]: ../oidc-auth/ +[8]: ../ldap-auth/ +[9]: ../oidc-auth/#oidc-configuration-example +[10]: ../../../api/enterprise/authproviders/ +[11]: ../ldap-auth/#ldap-configuration-examples +[12]: ../oidc-auth/#oidc-specification +[13]: ../ldap-auth/#ldap-specification +[14]: ../ad-auth/#ad-configuration-examples +[15]: ../ad-auth/#ad-specification diff --git a/content/sensu-go/6.12/operations/control-access/use-apikeys.md b/content/sensu-go/6.12/operations/control-access/use-apikeys.md new file mode 100644 index 0000000000..5e06a5503d --- /dev/null +++ b/content/sensu-go/6.12/operations/control-access/use-apikeys.md @@ -0,0 +1,168 @@ +--- +title: "Use API keys to authenticate to Sensu" +linkTitle: "Use API Keys" +guide_title: "Use API keys to authenticate to Sensu" +type: "guide" +description: "Sensu's API key feature improves integration efficiency, security, and administrative control. Read this guide to use Sensu's API key for authentication." +weight: 20 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: control-access +--- + +The Sensu API key feature (core/v2.APIKey) is a persistent universally unique identifier (UUID) that maps to a stored Sensu username. +The advantages of authenticating with API keys rather than [access tokens][1] include: + +- **More efficient integration**: Check and handler plugins and other code can integrate with the Sensu API without implementing the logic required to authenticate via the `/auth` API endpoint to periodically refresh the access token +- **Improved security**: API keys do not require providing a username and password in check or handler definitions +- **Better admin control**: API keys can be created and revoked without changing the underlying user's password...but keep in mind that API keys will continue to work even if the user's password changes + +API keys are cluster-wide resources, so only cluster admins can grant, view, and revoke them. + +{{% notice note %}} +**NOTE**: API keys are not supported for authentication providers such as LDAP and OIDC. +{{% /notice %}} + +## API key authentication + +Similar to the `Bearer [token]` Authorization header, `Key [api-key]` will be accepted as an Authorization header for authentication. + +For example, a JWT `Bearer [token]` Authorization header might be: + +{{< code shell >}} +curl -H "Authorization: Bearer $SENSU_ACCESS_TOKEN" http://127.0.0.1:8080/api/core/v2/namespaces/default/checks +{{< /code >}} + +If you're using `Key [api-key]` to authenticate instead, the Authorization header might be: + +{{< code shell >}} +curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/namespaces/default/checks +{{< /code >}} + +Here's an example request that uses API key authentication: + +{{< code shell >}} +curl -H "Authorization: Key 7f63b5bc-41f4-4b3e-b59b-5431afd7e6a2" http://127.0.0.1:8080/api/core/v2/namespaces/default/checks +{{< /code >}} + +A successful request will return the HTTP response code `HTTP/1.1 200 OK` and the definitions for the checks in the default namespace. + +## Sensuctl management commands + +{{% notice note %}} +**NOTE**: The API key resource is intentionally not compatible with [`sensuctl create`](../../../sensuctl/create-manage-resources/#create-resources). +{{% /notice %}} + +To use sensuctl to generate a new API key for the admin user, run: + +{{< code shell >}} +sensuctl api-key grant admin +{{< /code >}} + +The response will include the new API key: + +{{< code text >}} +Created: /api/core/v2/apikeys/7f63b5bc-41f4-4b3e-b59b-5431afd7e6a2 +{{< /code >}} + +To bypass username/password authentication for sensuctl, add the `--api-key` [global flag][2] to specify your API key with sensuctl commands. +For example: + +{{< code shell >}} +sensuctl --api-key 7f63b5bc-41f4-4b3e-b59b-5431afd7e6a2 event list +{{< /code >}} + +To get information about an API key: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl api-key info 7f63b5bc-41f4-4b3e-b59b-5431afd7e6a2 --format yaml +{{< /code >}} + +{{< code shell "Wrapped-JSON" >}} +sensuctl api-key info 7f63b5bc-41f4-4b3e-b59b-5431afd7e6a2 --format wrapped-json +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl api-key info 7f63b5bc-41f4-4b3e-b59b-5431afd7e6a2 --format json +{{< /code >}} + +{{< /language-toggle >}} + +The response will include information about the API key in the specified format: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: APIKey +api_version: core/v2 +metadata: + created_by: admin + name: 7f63b5bc-41f4-4b3e-b59b-5431afd7e6a2 +spec: + created_at: 1570718917 + username: admin +{{< /code >}} + +{{< code shell "Wrapped JSON" >}} +{ + "type": "APIKey", + "api_version": "core/v2", + "metadata": { + "name": "7f63b5bc-41f4-4b3e-b59b-5431afd7e6a2", + "created_by": "admin" + }, + "spec": { + "created_at": 1570718917, + "username": "admin" + } +} +{{< /code >}} + +{{< code json >}} +{ + "metadata": { + "name": "7f63b5bc-41f4-4b3e-b59b-5431afd7e6a2", + "created_by": "admin" + }, + "username": "admin", + "created_at": 1570718917 +} +{{< /code >}} + +{{< /language-toggle >}} + +To get a list of all API keys: + +{{< code shell >}} +sensuctl api-key list +{{< /code >}} + +The response lists all API keys along with the name of the user who created each key and the date and time each key was created: + +{{< code text >}} + Name Username Created At + ────────────────────────────────────── ────────── ─────────────────────────────── + 7f63b5bc-41f4-4b3e-b59b-5431afd7e6a2 admin 2019-10-10 14:48:37 -0700 PDT +{{< /code >}} + +To revoke an API key for the admin user: + +{{< code shell >}} +sensuctl api-key revoke 7f63b5bc-41f4-4b3e-b59b-5431afd7e6a2 --skip-confirm +{{< /code >}} + +The response will confirm that the API key is deleted: + +{{< code text >}} +Deleted +{{< /code >}} + + +[1]: ../../../api/other/auth/ +[2]: ../../../sensuctl/#use-global-flags-for-sensuctl-settings diff --git a/content/sensu-go/6.12/operations/deploy-sensu/_index.md b/content/sensu-go/6.12/operations/deploy-sensu/_index.md new file mode 100644 index 0000000000..a78a514c57 --- /dev/null +++ b/content/sensu-go/6.12/operations/deploy-sensu/_index.md @@ -0,0 +1,66 @@ +--- +title: "Deploy Sensu" +description: "Deploy Sensu, the flexible observability pipeline built to ease operator burden and meet the challenges of monitoring multi-cloud and ephemeral infrastructure." +product: "Sensu Go" +version: "6.12" +weight: 10 +layout: "single" +toc: true +menu: + sensu-go-6.12: + parent: operations + identifier: deploy-sensu +--- + +Use the information and instructions in the Deploy Sensu category to plan, install, configure, and deploy Sensu's flexible monitoring and observability pipeline. + +## Plan your Sensu deployment + +Find Sensu agent and backend requirements and networking and cloud recommendations in the [hardware requirements][1]. + +[Deployment architecture for Sensu][2] describes planning considerations and recommendations for a production-ready Sensu deployment, along with communication security details and diagrams showing single, clustered, and large-scale deployment architectures. + +## Install Sensu + +When you're ready to start using Sensu, the pathway you follow will depend on your monitoring and observability needs. +No matter which pathway you choose, you should begin with the [Install Sensu][3] guide. +If you just want to use Sensu locally, you can do that by installing Sensu according to the steps in the guide. +You can also use the Install Sensu guide to set up proof-of-concept and testing in a development environment. + +## Deploy Sensu in production + +To deploy Sensu for use outside of a local development environment, [install Sensu][3] and follow these guides to achieve a production-ready installation: + +1. [Generate certificates][4], which you will need to secure a Sensu cluster and its agents. +2. [Secure your Sensu installation][5] using the certificates you generate to make Sensu production-ready. +3. [Run a Sensu cluster][6], a group of three or more sensu-backend nodes connected to a shared database, to improve Sensu's availability, reliability, and durability. +4. [Reach multi-cluster visibility][7] with federation so you can gain visibility into the health of your infrastructure and services across multiple distinct Sensu instances within a single web UI and mirror your changes in one cluster to follower clusters. + +Read the [etcd replicators reference][9] to learn how the etcd-replicators datatype in the enterprise/federation/v1 API allows you to manage role-based access control (RBAC) resources in one place and mirror your changes to follower clusters. + +## Scale your Sensu implementation + +As the number of entities and checks in your Sensu implementation grows, so does the rate of events being written to the datastore. +In clustered etcd deployments, each event must be replicated to each cluster member, which increases network and disk IO utilization. + +Sensu's Enterprise datastore allows you to configure an external PostgreSQL instance for event storage so you can [scale your monitoring and observability workflows][13] beyond etcd’s 8GB limit. +Scale your Sensu implementation to many thousands of events per second, achieve much higher rates of event processing, and minimize the replication communication between etcd peers. + +Read the [datastore reference][14] for the Enterprise datastore requirements and specifications. + +For deployments at scale, [configuration management tools][12] can help ensure repeatable Sensu deployments and consistent configuration among Sensu backends. +Ansible, Chef, and Puppet have well-defined Sensu modules to help you get started. + + +[1]: hardware-requirements/ +[2]: deployment-architecture/ +[3]: install-sensu/ +[4]: generate-certificates/ +[5]: secure-sensu/ +[6]: cluster-sensu/ +[7]: use-federation/ +[8]: scale-event-storage/ +[9]: etcdreplicators/ +[12]: configuration-management/ +[13]: scale-event-storage/ +[14]: datastore/ diff --git a/content/sensu-go/6.12/operations/deploy-sensu/cluster-sensu.md b/content/sensu-go/6.12/operations/deploy-sensu/cluster-sensu.md new file mode 100644 index 0000000000..26ae33eba0 --- /dev/null +++ b/content/sensu-go/6.12/operations/deploy-sensu/cluster-sensu.md @@ -0,0 +1,493 @@ +--- +title: "Run a Sensu cluster" +linkTitle: "Run a Sensu Cluster" +guide_title: "Run a Sensu cluster" +type: "guide" +description: "Use clustering to improve Sensu's availability, reliability, and durability and manage lost backend nodes, prevent data loss, and distribute agent network load." +weight: 70 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: deploy-sensu +--- + +To deploy Sensu for use outside of a local development environment, first decide whether you want to run a Sensu cluster. + +A Sensu cluster is a group of at least three sensu-backend nodes, each connected to a shared database provided either by Sensu’s embedded etcd or an external etcd cluster. +Creating a Sensu cluster ultimately configures an [etcd cluster][2]. + +Clustering improves Sensu's availability, reliability, and durability. +It allows you to absorb the loss of a backend node, prevent data loss, and distribute the network load of agents. +If you have a healthy clustered backend, you only need to make [Sensu API][20] calls to any one of the cluster members. +The cluster protocol will replicate your changes to all cluster members. + +Scaling a single backend to a cluster or migrating a cluster from cleartext HTTP to encrypted HTTPS without downtime can require [a number of tedious steps][14]. +For this reason, we recommend that you **decide whether your deployment will require clustering as part of your initial planning effort**. + +No matter whether you deploy a single backend or a clustered configuration, begin by securing Sensu with transport layer security (TLS). +The first step in setting up TLS is to [generate the certificates you need][13]. +Then, follow our [Secure Sensu][16] guide to make Sensu production-ready. + +After you've secured Sensu, continue reading this document to [set up][2] and [update][1] a clustered configuration. + +{{% notice note %}} +**NOTE**: We recommend using a load balancer to evenly distribute agent connections across a cluster. +{{% /notice %}} + +## Configure a cluster + +The sensu-backend arguments for its store mirror the [etcd configuration flags][3], but the Sensu configuration options are prefixed with `etcd`. +For more detailed descriptions of the different arguments, read the [etcd documentation][4] or [Sensu backend reference][15]. + +You can configure a Sensu cluster in a couple different ways — we'll show you a few below — but you should adhere to some etcd cluster guidelines as well: + +> The recommended etcd cluster size is 3, 5 or 7, which is decided by the fault tolerance requirement. A 7-member cluster can provide enough fault tolerance in most cases. While a larger cluster provides better fault tolerance, the write performance reduces since data needs to be replicated to more machines. It is recommended to have an odd number of members in a cluster. Having an odd cluster size doesn't change the number needed for majority, but you gain a higher tolerance for failure by adding the extra member. *[etcd2 Admin Guide][18]* + +We also recommend using stable platforms to support your etcd instances (review [etcd's supported platforms][5]). + +{{% notice note %}} +**NOTE**: If a cluster member is started before it is configured to join a cluster, the member will persist its prior configuration to disk. +For this reason, you must remove any previously started member's etcd data by stopping sensu-backend and deleting the contents of `/var/lib/sensu/sensu-backend/etcd` before proceeding with cluster configuration. +{{% /notice %}} + +### Docker + +If you prefer to stand up your Sensu cluster within Docker containers, check out the Sensu Go [Docker configuration][7]. +This configuration defines three sensu-backend containers and three sensu-agent containers. + +### Traditional computer instance + +{{% notice note %}} +**NOTE**: The remainder of this guide describes on-disk configuration. +If you are using an ephemeral computer instance, you can use `sensu-backend start --help` to list etcd command line flags. +The configuration file entries in the rest of this guide translate to `sensu-backend` flags. +{{% /notice %}} + +#### Sensu backend configuration + +{{% notice warning %}} +**WARNING**: You must update the default configuration for Sensu's embedded etcd with an explicit, non-default configuration to secure etcd communication in transit. +If you do not properly configure secure etcd communication, your Sensu configuration will be vulnerable to unauthorized manipulation via etcd client connections. +{{% /notice %}} + +The examples in this section are configuration snippets from `/etc/sensu/backend.yml` using a three-node cluster. +The nodes are named `backend-1.example.com`, `backend-2.example.com` and `backend-3.example.com` with IP addresses `10.0.0.1`, `10.0.0.2` and `10.0.0.3`, respectively. + +{{% notice note %}} +**NOTE**: This backend configuration assumes you have set up and installed the sensu-backend on all the nodes used in your cluster. +Follow the [Install Sensu](../install-sensu/) guide if you have not already done this. +{{% /notice %}} + +**Store configuration for backend-1.example.com/10.0.0.1** + +{{< code yml >}} +etcd-advertise-client-urls: "https://10.0.0.1:2379" +etcd-listen-client-urls: "https://10.0.0.1:2379" +etcd-listen-peer-urls: "https://0.0.0.0:2380" +etcd-initial-cluster: "backend-1.example.com=https://10.0.0.1:2380,backend-2.example.com=https://10.0.0.2:2380,backend-3.example.com=https://10.0.0.3:2380" +etcd-initial-advertise-peer-urls: "https://10.0.0.1:2380" +etcd-initial-cluster-state: "new" +etcd-initial-cluster-token: "unique_token_for_this_cluster" +etcd-name: "backend-1.example.com" +{{< /code >}} + +**Store configuration for backend-2.example.com/10.0.0.2** + +{{< code yml >}} +etcd-advertise-client-urls: "https://10.0.0.2:2379" +etcd-listen-client-urls: "https://10.0.0.2:2379" +etcd-listen-peer-urls: "https://0.0.0.0:2380" +etcd-initial-cluster: "backend-1.example.com=https://10.0.0.1:2380,backend-2.example.com=https://10.0.0.2:2380,backend-3.example.com=https://10.0.0.3:2380" +etcd-initial-advertise-peer-urls: "https://10.0.0.2:2380" +etcd-initial-cluster-state: "new" +etcd-initial-cluster-token: "unique_token_for_this_cluster" +etcd-name: "backend-2.example.com" +{{< /code >}} + +**Store configuration for backend-3.example.com/10.0.0.3** + +{{< code yml >}} +etcd-advertise-client-urls: "https://10.0.0.3:2379" +etcd-listen-client-urls: "https://10.0.0.3:2379" +etcd-listen-peer-urls: "https://0.0.0.0:2380" +etcd-initial-cluster: "backend-1.example.com=https://10.0.0.1:2380,backend-2.example.com=https://10.0.0.2:2380,backend-3.example.com=https://10.0.0.3:2380" +etcd-initial-advertise-peer-urls: "https://10.0.0.3:2380" +etcd-initial-cluster-state: "new" +etcd-initial-cluster-token: "unique_token_for_this_cluster" +etcd-name: "backend-3.example.com" +{{< /code >}} + +{{% notice warning %}} +**WARNING**: To properly secure etcd communication, replace the default URLs for `etcd-advertise-client-urls`, `etcd-listen-client-urls`, `etcd-listen-peer-urls`, and `etcd-initial-cluster` in the store configurations for your backends with non-default values.

    +Specify the same `etcd-initial-cluster-token` value for all three backends. +This allows etcd to generate unique cluster IDs and member IDs even for clusters that have otherwise identical configurations and prevents cross-cluster-interaction. +{{% /notice %}} + +After you configure each node as described in these examples, start each sensu-backend: + +{{< code shell >}} +sudo systemctl start sensu-backend +{{< /code >}} + +##### Add Sensu agents to clusters + +Each Sensu agent should have the following entries in `/etc/sensu/agent.yml` to ensure the agent is aware of all cluster members. +This allows the agent to reconnect to a working backend if the backend it is currently connected to goes into an unhealthy state. + +Here is an example backend-url configuration for all agents connecting to the cluster over WebSocket: + +{{< code yml >}} +backend-url: + - "ws://10.0.0.1:8081" + - "ws://10.0.0.2:8081" + - "ws://10.0.0.3:8081" +{{< /code >}} + +You should now have a highly available Sensu cluster! +Confirm cluster health and try other cluster management commands with [sensuctl][6]. + +## Manage and monitor clusters with sensuctl + +[Sensuctl][17] includes several commands to help you manage and monitor your cluster. +Run `sensuctl cluster -h` for additional help information. + +### Get cluster health status + +Get cluster health status and etcd alarm information: + +{{< code shell >}} +sensuctl cluster health +{{< /code >}} + +The cluster health response will list the health status for each cluster member, similar to this example: + +{{< code text >}} + ID Name Error Healthy +────────────────── ────────────────────── ─────────────────────────────────────────────────── ───────── +a32e8f613b529ad4 backend-1.example.com true +c3d9f4b8d0dd1ac9 backend-2.example.com dial tcp 10.0.0.2:2379: connect: connection refused false +c8f63ae435a5e6bf backend-3.example.com true +{{< /code >}} + +### Add a cluster member + +To add a new member node to an existing cluster: + +1. Configure the new node's store in its `/etc/sensu/backend.yml` configuration file. +For the new node `backend-4.example.com` with IP address `10.0.0.4`: + + {{< code yml >}} +etcd-advertise-client-urls: "https://10.0.0.4:2379" +etcd-listen-client-urls: "https://10.0.0.4:2379" +etcd-listen-peer-urls: "https://0.0.0.0:2380" +etcd-initial-cluster: "backend-1.example.com=https://10.0.0.1:2380,backend-2.example.com=https://10.0.0.2:2380,backend-3.example.com=https://10.0.0.3:2380,backend-4.example.com=https://10.0.0.4:2380" +etcd-initial-advertise-peer-urls: "https://10.0.0.4:2380" +etcd-initial-cluster-state: "existing" +etcd-initial-cluster-token: "unique_token_for_this_cluster" +etcd-name: "backend-4.example.com" +{{< /code >}} + + {{% notice note %}} +**NOTE**: To make sure the new member is added to the correct cluster, specify the same `etcd-initial-cluster-token` value that you used for the other members in the cluster.

    +Also, when you are adding a cluster member, make sure the `etcd-initial-cluster-state` value is `existing`, **not** `new`. +{{% /notice %}} + +2. Run the sensuctl command to add the new cluster member: + + {{< code shell >}} +sensuctl cluster member-add backend-4.example.com https://10.0.0.4:2380 +{{< /code >}} + + You will receive a sensuctl response to confirm that the new member was added: + + {{< code text >}} +added member 2f7ae42c315f8c2d to cluster +{{< /code >}} + +3. Start the new backend: + + {{< code shell >}} +sudo systemctl start sensu-backend +{{< /code >}} + +4. Add the new cluster member's WebSocket backend-url in `/etc/sensu/agent.yml` for all agents that connect to the cluster over WebSocket: + + {{< code yml >}} +backend-url: + - "ws://10.0.0.1:8081" + - "ws://10.0.0.2:8081" + - "ws://10.0.0.3:8081" + - "ws://10.0.0.4:8081" +{{< /code >}} + +### List cluster members + +List the ID, name, peer URLs, and client URLs of all nodes in a cluster: + +{{< code shell >}} +sensuctl cluster member-list +{{< /code >}} + +You will receive a sensuctl response that lists all cluster members: + +{{< code text >}} + ID Name Peer URLs Client URLs +────────────────── ─────────────────────── ───────────────────────── ───────────────────────── +a32e8f613b529ad4 backend-1.example.com https://10.0.0.1:2380 https://10.0.0.1:2379 +c3d9f4b8d0dd1ac9 backend-2.example.com https://10.0.0.2:2380 https://10.0.0.2:2379 +c8f63ae435a5e6bf backend-3.example.com https://10.0.0.3:2380 https://10.0.0.3:2379 +2f7ae42c315f8c2d backend-4.example.com https://10.0.0.4:2380 https://10.0.0.4:2379 +{{< /code >}} + +### Remove a cluster member + +Remove a faulty or decommissioned member node from a cluster: + +{{< code shell >}} +sensuctl cluster member-remove 2f7ae42c315f8c2d +{{< /code >}} + +You will receive a sensuctl response to confirm that the cluster member was removed: + +{{< code text >}} +Removed member 2f7ae42c315f8c2d from cluster +{{< /code >}} + +### Replace a faulty cluster member + +To replace a faulty cluster member to restore a cluster's health: + +1. Get cluster health status and etcd alarm information: +{{< code shell >}} +sensuctl cluster health +{{< /code >}} + + In the response, for a faulty cluster member, the Error column will include an error message and the Healthy column will list `false`. + In this example, the response indicates that cluster member `backend-4` is faulty: +{{< code text >}} + ID Name Error Healthy +────────────────── ─────────────────────── ─────────────────────────────────────────────────── ───────── +a32e8f613b529ad4 backend-1.example.com true +c3d9f4b8d0dd1ac9 backend-2.example.com true +c8f63ae435a5e6bf backend-3.example.com true +2f7ae42c315f8c2d backend-4.example.com dial tcp 10.0.0.4:2379: connect: connection refused false + +{{< /code >}} + +2. Remove the faulty cluster member — in this example, `backend-4` — using its ID. +Removing the faulty cluster member prevents the cluster size from growing. +{{< code shell >}} +sensuctl cluster member-remove 2f7ae42c315f8c2d +{{< /code >}} + + The response should indicate that the cluster member was removed: +{{< code text >}} +Removed member 2f7ae42c315f8c2d from cluster +{{< /code >}} + +3. Follow the steps in [Add a cluster member][22] to configure the replacement cluster member. +{{% notice note %}} +**NOTE**: You can use the same name and IP address as the removed faulty member for the replacement cluster member. +When updating the replacement member's backend configuration file, make sure the `etcd-initial-cluster-state` value is `existing`, **not** `new`. +{{% /notice %}} + +If replacing the faulty cluster member does not resolve the problem, read the [etcd operations guide][12] for more information. + +### Update a cluster member + +Update the peer URLs of a member in a cluster: + +{{< code shell >}} +sensuctl cluster member-update c8f63ae435a5e6bf https://10.0.0.4:2380 +{{< /code >}} + +You will receive a sensuctl response to confirm that the cluster member was updated: + +{{< code text >}} +Updated member with ID c8f63ae435a5e6bf in cluster +{{< /code >}} + +## Cluster security + +Read [Secure Sensu][16] for information about cluster security. + +## Use an external etcd cluster + +{{% notice warning %}} +**WARNING**: You must update the example configuration for external etcd with an explicit, non-default configuration to secure etcd communication in transit. +If you do not properly configure secure etcd communication, your Sensu configuration will be vulnerable to unauthorized manipulation via etcd client connections. +{{% /notice %}} + +To use Sensu with an external etcd cluster, you must have etcd 3.3.2 or newer. +To stand up an external etcd cluster, follow etcd's [clustering guide][2] using the same store configuration. +Do not configure external etcd in Sensu via backend command line flags or the backend configuration file (`/etc/sensu/backend.yml`). + +### Configure key space access + +Follow these steps to configure read and write access to the `/sensu.io/` key space for your users so you can initialize a backend that uses etcd authentication. + +1. Add the `sensu` user: +{{< highlight shell >}} +etcdctl user add sensu +{{< /highlight >}} + +2. Enter the `sensu` user password when prompted. + +3. Create the `sensu_readwrite` role: +{{< highlight shell >}} +etcdctl role add sensu_readwrite +{{< /highlight >}} + +4. Grant read/write permissions to the `sensu_readwrite` role under the `/sensu.io/` key space: +{{< highlight shell >}} +etcdctl role grant-permission sensu_readwrite readwrite --from-key '/sensu.io/' +{{< /highlight >}} + +5. Grant the `sensu_readwrite` role to the `sensu` user: +{{< highlight shell >}} +etcdctl user grant-role sensu sensu_readwrite +{{< /highlight >}} + +6. Confirm that the grant is configured correctly: +{{< highlight shell >}} +/opt/etcd/etcdctl user get USERNAME --detail +{{< /highlight >}} + + You should see the following output: +{{< highlight text >}} +User: USERNAME + +Role sensu_readwrite +KV Read: + [/sensu.io/, +KV Write: + [/sensu.io/, +{{< /highlight >}} + +Etcd does not enable authentication by default, so additional configuration may be needed before etcd will enforce these controls. +See the [etcd operators documentation][12] for details. + +### Start etcd + +In this example, you will enable client-to-server and peer communication authentication [using self-signed TLS certificates][13]. +To start etcd for `backend-1.example.com` based on the [three-node configuration example][19]: + +{{< code shell >}} +etcd \ +--listen-client-urls "https://10.0.0.1:2379" \ +--advertise-client-urls "https://10.0.0.1:2379" \ +--listen-peer-urls "https://10.0.0.1:2380" \ +--initial-cluster "backend-1.example.com=https://10.0.0.1:2380,backend-2.example.com=https://10.0.0.2:2380,backend-3.example.com=https://10.0.0.3:2380" \ +--initial-advertise-peer-urls "https://10.0.0.1:2380" \ +--initial-cluster-state "new" \ +--name "backend-1.example.com" \ +--trusted-ca-file=./ca.pem \ +--cert-file=./backend-1.example.com.pem \ +--key-file=./backend-1.example.com-key.pem \ +--client-cert-auth \ +--peer-trusted-ca-file=./ca.pem \ +--peer-cert-file=./backend-1.example.com.pem \ +--peer-key-file=./backend-1.example.com-key.pem \ +--peer-client-cert-auth \ +--auto-compaction-mode revision \ +--auto-compaction-retention 2 +{{< /code >}} + +{{% notice note %}} +**NOTE**: Without the `auto-compaction-mode` and `auto-compaction-retention` flags, your database may quickly reach etcd's maximum database size limit. +{{% /notice %}} + +Tell Sensu to use this external etcd data source by adding the `sensu-backend` flag `--no-embed-etcd` to the original configuration and the path to a client certificate created using your CA: + +{{< code shell >}} +sensu-backend start \ +--etcd-trusted-ca-file=./ca.pem \ +--etcd-cert-file=./backend-1.example.com.pem \ +--etcd-key-file=./backend-1.example.com-key.pem \ +--etcd-client-urls='https://10.0.0.1:2379 https://10.0.0.2:2379 https://10.0.0.3:2379' \ +--no-embed-etcd +{{< /code >}} + +{{% notice note %}} +**NOTE**: The etcd and sensu-backend certificates must share a CA, and the `etcd-client-urls` value must be a space-delimited list or a YAML array. +{{% /notice %}} + +### Authenticate with username and password for external etcd + +Managed database services (database-as-a-service, or DBaaS) often support external etcd authentication via username and password rather than client certificates. + +To use username and password authentication to connect to external etcd, add the `SENSU_BACKEND_ETCD_CLIENT_USERNAME` and `SENSU_BACKEND_ETCD_CLIENT_PASSWORD` [environment variables][28] to the environment file. +Replace `` and `` with the username and password you use for your external etcd provider: + +{{< code shell >}} +SENSU_BACKEND_ETCD_CLIENT_USERNAME= +SENSU_BACKEND_ETCD_CLIENT_PASSWORD= +{{< /code >}} + +Read [Configuration via environment variables][28] to learn how to create and save environment variables. + +The `SENSU_BACKEND_ETCD_CLIENT_USERNAME` and `SENSU_BACKEND_ETCD_CLIENT_PASSWORD` environment variables do not have corresponding configuration flags. +To use username/passsword authentication for external etcd, you must configure these environment variables in the environment file. + +## Migrate from embedded etcd to external etcd + +To migrate from embedded etcd to external etcd, first decide whether you need to migrate all of your etcd data or just your Sensu configurations. + +If you need to migrate all etcd data, you must create an [etcd snapshot][9]. +Use the snapshot to [restore][25] your entire cluster after setting up the new external cluster. + +If you need to migrate only your Sensu configuration, you can use [sensuctl dump][24] to create a backup and use [sensuctl create][26] to import your configuration to the new external cluster. + +{{% notice note %}} +**NOTE**: The sensuctl dump command does not export user passwords, and sensuctl create does not restore API keys from a sensuctl dump backup. +For this reason, you must use the [etcd snapshot and restore process](https://etcd.io/docs/latest/op-guide/recovery/) to migrate your entire embedded cluster to external etcd. +{{% /notice %}} + +After you create the backups you need, follow [Use an external etcd cluster][27] to configure Sensu to use the external cluster as your datastore. + +## Troubleshoot clusters + +### Failure modes + +Read the [etcd failure modes documentation][8] for information about cluster failure modes. + +### Disaster recovery + +Read [Restore your Sensu configuration for disaster recovery][29] for instructions for recovering a Sensu cluster as well as best practices for backups. + +### Redeploy a cluster + +To redeploy a cluster due to an issue like loss of quorum among cluster members, etcd corruption, or hardware failure, read [Remove and redeploy a cluster][23]. + + +[1]: https://etcd.io/docs/latest/op-guide/runtime-configuration/ +[2]: https://etcd.io/docs/latest/op-guide/clustering/ +[3]: https://etcd.io/docs/latest/op-guide/configuration/ +[4]: https://etcd.io/docs/latest/ +[5]: https://etcd.io/docs/latest/platforms/ +[6]: #manage-and-monitor-clusters-with-sensuctl +[7]: https://github.com/sensu/sensu-go/blob/main/docker-compose.yaml +[8]: https://etcd.io/docs/latest/op-guide/failures/ +[9]: https://etcd.io/docs/latest/op-guide/recovery/ +[10]: https://github.com/cloudflare/cfssl +[11]: https://etcd.io/docs/latest/op-guide/clustering/#self-signed-certificates +[12]: https://etcd.io/docs/latest/op-guide/ +[13]: ../generate-certificates/ +[14]: https://etcd.io/docs/latest/op-guide/runtime-configuration/ +[15]: ../../../observability-pipeline/observe-schedule/backend/#datastore-and-cluster-configuration +[16]: ../secure-sensu/ +[17]: ../../../sensuctl/ +[18]: https://etcd.io/docs/current/dev-internal/discovery_protocol/#specifying-the-expected-cluster-size +[19]: #sensu-backend-configuration +[20]: ../../../api/ +[21]: ../install-sensu/ +[22]: #add-a-cluster-member +[23]: ../../maintain-sensu/troubleshoot/#remove-and-redeploy-a-cluster +[24]: ../../../sensuctl/back-up-recover/ +[25]: https://etcd.io/docs/v3.5/op-guide/recovery/#restoring-a-cluster +[26]: ../../../sensuctl/back-up-recover/#restore-resources-from-backup +[27]: #use-an-external-etcd-cluster +[28]: ../../../observability-pipeline/observe-schedule/backend/#configuration-via-environment-variables +[29]: ../../maintain-sensu/disaster-recovery/ diff --git a/content/sensu-go/6.12/operations/deploy-sensu/configuration-management.md b/content/sensu-go/6.12/operations/deploy-sensu/configuration-management.md new file mode 100644 index 0000000000..0df61d5dd8 --- /dev/null +++ b/content/sensu-go/6.12/operations/deploy-sensu/configuration-management.md @@ -0,0 +1,47 @@ +--- +title: "Configuration management" +linkTitle: "Configuration Management" +description: "Configuration management tools can help you deploy Sensu in production and at scale. Learn more about Sensu integrations." +weight: 40 +product: "Sensu Go" +version: "6.12" +menu: + sensu-go-6.12: + parent: deploy-sensu +--- + +We recommend using configuration management tools to deploy Sensu in production and at scale. + +- Pin versions of Sensu-related software to ensure repeatable Sensu deployments. +- Ensure consistent configuration between Sensu backends. + +The configuration management tools listed here have well-defined Sensu modules to help you get started. + +## Ansible + +The [Ansible][5] role to deploy and manage Sensu Go is available in the [Sensu Go Ansible Collection][6]. + +The [Sensu Go Ansible Collection documentation site][9] includes installation instructions, example playbooks, and module references. + +## Chef + +The [Chef][3] cookbook for installing and configuring Sensu is available in the [Sensu Go Chef Cookbook][4]. + +[Contact us][8] for more information about Sensu + Chef. + +## Puppet + +The [Puppet][1] module to install Sensu is available in the [Sensu Puppet Module][2]. + +Sensu partnered with [Tailored Automation][7] to enhance the Puppet module with new features and bug fixes. + + +[1]: https://puppet.com/ +[2]: https://forge.puppet.com/modules/sensu/sensu +[3]: https://www.chef.io/ +[4]: https://supermarket.chef.io/cookbooks/sensu-go +[5]: https://www.ansible.com/ +[6]: https://galaxy.ansible.com/sensu/sensu_go +[7]: https://tailoredautomation.io/ +[8]: https://monitoringlove.sensu.io/chef +[9]: https://sensu.github.io/sensu-go-ansible/ diff --git a/content/sensu-go/6.12/operations/deploy-sensu/datastore.md b/content/sensu-go/6.12/operations/deploy-sensu/datastore.md new file mode 100644 index 0000000000..f61487d8a2 --- /dev/null +++ b/content/sensu-go/6.12/operations/deploy-sensu/datastore.md @@ -0,0 +1,559 @@ +--- +title: "Datastore reference" +linkTitle: "Datastore Reference" +reference_title: "Datastore" +type: "reference" +description: "Sensu stores observability events using an etcd database by default. You can also configure external PostgreSQL for enterprise-scale event storage." +weight: 160 +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: deploy-sensu +--- + +Sensu stores the most recent event for each entity and check pair using either an etcd (default) or PostgreSQL database. + +You can access observability event data with the [Sensu web UI][9] Events page, [`sensuctl event` commands][10], and [core/v2/events API endpoints][11]. +For longer retention of observability event data, integrate Sensu with a time-series database like [InfluxDB][12] or a searchable index like ElasticSearch or Splunk. + +## etcd and PostgreSQL version compatibility + +Sensu requires at least etcd 3.3.2 and is tested against etcd 3.5. +etcd version 3.4.0 is compatible with Sensu but may result in slower performance. + +Sensu supports PostgreSQL 9.5 and later, including [Amazon Relational Database Service][3] (Amazon RDS) when configured with the PostgreSQL engine. + +## Use default event storage + +By default, Sensu uses its embedded etcd database to store configuration and event data. +This embedded database allows you to get started with Sensu without deploying a complete, scalable architecture. +Sensu's default embedded etcd configuration listens for unencrypted communication on [ports][19] 2379 (client requests) and 2380 (peer communication). + +Sensu can be configured to disable the embedded etcd database and use one or more [external etcd nodes][8] for configuration and event storage instead. +To stand up an external etcd cluster, follow etcd's [clustering guide][7] using the same store configuration. +Do not configure external etcd in Sensu via backend command line flags or the backend configuration file (`/etc/sensu/backend.yml`). + +As your deployment grows beyond the proof-of-concept stage, review [Deployment architecture for Sensu][6] for more information about deployment considerations and recommendations for a production-ready Sensu deployment. + +## Scale event storage + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access enterprise-scale event storage in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} + +Sensu supports using an external PostgreSQL instance for event storage in place of etcd. +PostgreSQL can handle significantly higher volumes of Sensu events, which allows you to scale Sensu beyond etcd's 8GB limit. + +When configured with a PostgreSQL event store, Sensu connects to PostgreSQL to store and retrieve event data in place of etcd. +Etcd continues to store Sensu entity and configuration data. +You can access event data stored in PostgreSQL using the same Sensu web UI, API, and sensuctl processes as etcd-stored events. + +Read the [PostgreSQL documentation][14] to install and configure PostgreSQL. + +### PostgreSQL requirements + +For optimal performance, we recommend the following PostgreSQL configuration parameters and settings as a starting point for your `postgresql.conf` file: + +{{< code postgresql >}} +max_connections = 200 + +shared_buffers = 10GB + +maintenance_work_mem = 1GB + +vacuum_cost_delay = 10ms +vacuum_cost_limit = 10000 + +bgwriter_delay = 50ms +bgwriter_lru_maxpages = 1000 + +max_worker_processes = 8 +max_parallel_maintenance_workers = 2 +max_parallel_workers_per_gather = 2 +max_parallel_workers = 8 + +synchronous_commit = off + +wal_sync_method = fdatasync +wal_writer_delay = 5000ms +max_wal_size = 5GB +min_wal_size = 1GB + +checkpoint_completion_target = 0.9 + +autovacuum_naptime = 10s +autovacuum_vacuum_scale_factor = 0.05 +autovacuum_analyze_scale_factor = 0.025 +{{< /code >}} + +Adjust the parameters and settings as needed based on your hardware and the performance you observe. +Read the [PostgreSQL parameters documentation][20] for information about setting parameters. + +### Configure the PostgreSQL event store + +At the time when you enable the PostgreSQL event store, event data cuts over from etcd to PostgreSQL. +This results in a loss of recent event history. +No restarts or Sensu backend configuration changes are required to enable the PostgreSQL event store. + +When you successfully enable PostgreSQL as the Sensu Go event store, the Sensu backend log will include a message like this: + +{{< code shell >}} +Mar 10 17:44:45 sensu-centos sensu-backend[1365]: {"component":"store-providers","level":"warning","msg":"switched event store to postgres","time":"2020-03-10T17:44:45Z"} +{{< /code >}} + +After you [install and configure PostgreSQL][14], configure Sensu by creating a `PostgresConfig` resource like the following example. +Review the [datastore specification][18] for more information. + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: PostgresConfig +api_version: store/v1 +metadata: + name: my-postgres +spec: + batch_buffer: 0 + batch_size: 1 + batch_workers: 0 + dsn: "postgresql://user:secret@host:port/dbname" + max_conn_lifetime: 5m + max_idle_conns: 2 + pool_size: 20 + strict: true + enable_round_robin: true +{{< /code >}} + +{{< code json >}} +{ + "type": "PostgresConfig", + "api_version": "store/v1", + "metadata": { + "name": "my-postgres" + }, + "spec": { + "batch_buffer": 0, + "batch_size": 1, + "batch_workers": 0, + "dsn": "postgresql://user:secret@host:port/dbname", + "max_conn_lifetime": "5m", + "max_idle_conns": 2, + "pool_size": 20, + "strict": true, + "enable_round_robin": true + } +} +{{< /code >}} + +{{< /language-toggle >}} + +Save your `PostgresConfig` resource definition to a file (in this example, `postgres.yml` or `postgres.json`). +Then, use sensuctl [configured as the admin user][1] to activate the PostgreSQL event store. + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl create --file postgres.yml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl create --file postgres.json +{{< /code >}} + +{{< /language-toggle >}} + +To update your Sensu PostgreSQL configuration, repeat the `sensuctl create` process. +You can expect PostgreSQL status updates in the [Sensu backend logs][2] at the `warn` log level and PostgreSQL error messages in the [Sensu backend logs][2] at the `error` log level. + +#### Use environment variables to configure PostgreSQL + +The Sensu backend uses the [libpq][23] library to make connections to PostgreSQL. +libpq supports a number of [environment variables][21] that can be injected into the PostgreSQL data source name (DSN). +Sensu loads these environment variables at runtime using the system's environment variable file. + +You can use the libpq environment variables to connect to PostgreSQL without exposing sensitive information, like usernames and passwords, in your PostgreSQL configuration. +To do this, [define the libpq environment variables][22] as described in the backend reference. +Sensu automatically looks up these environment variables, so you do not need to reference them in your PostgresConfig definition. + +For example, to use libpq environment variables to define the PostgreSQL username, password, port, and database name in the [Sensu backend environment file][22]: + +{{< code shell >}} +PGUSER= +PGPASSWORD= +PGPORT=5432 +PGDATABASE=sensu_events +{{< /code >}} + +With these environment variables defined, the PostgreSQL configuration does not need to include the username, password, port, or database name: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: PostgresConfig +api_version: store/v1 +metadata: + name: postgres_datastore +spec: + dsn: "postgresql://postgres.example.com" + pool_size: 20 + strict: true +{{< /code >}} + +{{< code json >}} +{ + "type": "PostgresConfig", + "api_version": "store/v1", + "metadata": { + "name": "postgres_datastore" + }, + "spec": { + "dsn": "postgresql://postgres.example.com", + "pool_size": 20, + "strict": true + } +} +{{< /code >}} + +{{< /language-toggle >}} + +### Disable the PostgreSQL event store + +To disable the PostgreSQL event store, use `sensuctl delete` with your `PostgresConfig` resource definition file: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl delete --file postgres.yml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl delete --file postgres.json +{{< /code >}} + +{{< /language-toggle >}} + +The Sensu backend log will include a message to record that you successfully disabled PostgreSQL as the Sensu Go event store: + +{{< code shell >}} +Mar 10 17:35:04 sensu-centos sensu-backend[1365]: {"component":"store-providers","level":"warning","msg":"switched event store to etcd","time":"2020-03-10T17:35:04Z"} +{{< /code >}} + +When you disable the PostgreSQL event store, event data cuts over from PostgreSQL to etcd, which results in a loss of recent event history. +No restarts or Sensu backend configuration changes are required to disable the PostgreSQL event store. + +## Datastore specification + +### Top-level attributes + +api_version | | +-------------|------ +description | Top-level attribute that specifies the Sensu API group and version. For PostgreSQL datastore configs, the `api_version` should be `store/v1`. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +api_version: store/v1 +{{< /code >}} +{{< code json >}} +{ + "api_version": "store/v1" +} +{{< /code >}} +{{< /language-toggle >}} + +metadata | | +-------------|------ +description | Top-level scope that contains the PostgreSQL datastore `name` and `created_by` field. +required | true +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +metadata: + name: my-postgres + created_by: admin +{{< /code >}} +{{< code json >}} +{ + "metadata": { + "name": "my-postgres", + "created_by": "admin" + } +} +{{< /code >}} +{{< /language-toggle >}} + +spec | | +-------------|------ +description | Top-level map that includes the PostgreSQL datastore config [spec attributes][17]. +required | true +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +spec: + batch_buffer: 0 + batch_size: 1 + batch_workers: 0 + dsn: 'postgresql://user:secret@host:port/dbname' + max_conn_lifetime: 5m + max_idle_conns: 2 + pool_size: 20 + strict: true + enable_round_robin: true +{{< /code >}} +{{< code json >}} +{ + "spec": { + "batch_buffer": 0, + "batch_size": 1, + "batch_workers": 0, + "dsn": "postgresql://user:secret@host:port/dbname", + "max_conn_lifetime": "5m", + "max_idle_conns": 2, + "pool_size": 20, + "strict": true, + "enable_round_robin": true + } +} +{{< /code >}} +{{< /language-toggle >}} + +type | | +-------------|------ +description | Top-level attribute that specifies the [`sensuctl create`][16] resource type. PostgreSQL datastore configs should always be type `PostgresConfig`. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +type: PostgresConfig +{{< /code >}} +{{< code json >}} +{ + "type": "PostgresConfig" +} +{{< /code >}} +{{< /language-toggle >}} + +### Metadata attributes + +| created_by | | +-------------|------ +description | Username of the Sensu user who created the datastore or last updated the datastore. Sensu automatically populates the `created_by` field when the datastore is created or updated. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +created_by: admin +{{< /code >}} +{{< code json >}} +{ + "created_by": "admin" +} +{{< /code >}} +{{< /language-toggle >}} + +name | | +-------------|------ +description | PostgreSQL datastore name used internally by Sensu. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +name: my-postgres +{{< /code >}} +{{< code json >}} +{ + "name": "my-postgres" +} +{{< /code >}} +{{< /language-toggle >}} + +### Spec attributes + +batch_buffer | | +-------------|------ +description | Maximum number of requests to buffer in memory.
    {{% notice warning %}} +**WARNING**: The batcher is sensitive to configuration values, and some `batch_buffer`, `batch_size`, and `batch_workers` combinations will not work optimally. We do not recommend configuring this attribute while we are testing and improving it. +{{% /notice %}} +required | false +default | 0 +type | Integer +example | {{< language-toggle >}} +{{< code yml >}} +batch_buffer: 0 +{{< /code >}} +{{< code json >}} +{ + "batch_buffer": 0 +} +{{< /code >}} +{{< /language-toggle >}} + +batch_size | | +-------------|------ +description | Number of requests in each PostgreSQL write transaction, as specified in the PostgreSQL configuration.
    {{% notice warning %}} +**WARNING**: The batcher is sensitive to configuration values, and some `batch_buffer`, `batch_size`, and `batch_workers` combinations will not work optimally. We do not recommend configuring this attribute while we are testing and improving it. +{{% /notice %}} +required | false +default | 1 +type | Integer +example | {{< language-toggle >}} +{{< code yml >}} +batch_size: 1 +{{< /code >}} +{{< code json >}} +{ + "batch_size": 1 +} +{{< /code >}} +{{< /language-toggle >}} + +batch_workers | | +-------------|------ +description | Number of Goroutines sending data to PostgreSQL, as specified in the PostgreSQL configuration.
    {{% notice warning %}} +**WARNING**: The batcher is sensitive to configuration values, and some `batch_buffer`, `batch_size`, and `batch_workers` combinations will not work optimally. We do not recommend configuring this attribute while we are testing and improving it. +{{% /notice %}} +required | false +default | Current PostgreSQL pool size +type | Integer +example | {{< language-toggle >}} +{{< code yml >}} +batch_workers: 0 +{{< /code >}} +{{< code json >}} +{ + "batch_workers": 0 +} +{{< /code >}} +{{< /language-toggle >}} + +dsn | | +-------------|------ +description | Data source name. Specified as a URL or [PostgreSQL connection string][15]. The Sensu backend uses the Go pq library, which supports a [subset of the PostgreSQL libpq connection string parameters][4].

    To avoid exposing sensitive information in the `dsn` attribute, [configure PostgreSQL with environment variables][24]. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +dsn: 'postgresql://user:secret@host:port/dbname' +{{< /code >}} +{{< code json >}} +{ + "dsn": "postgresql://user:secret@host:port/dbname" +} +{{< /code >}} +{{< /language-toggle >}} + + + +enable_round_robin | | +-------------|------ +description | If `true`, enables [round robin scheduling][5] on PostgreSQL. Any existing round robin scheduling will stop and migrate to PostgreSQL as entities check in with keepalives. Sensu will gradually delete the existing etcd scheduler state as keepalives on the etcd scheduler keys expire over time. Otherwise, `false`.

    We recommend using PostgreSQL rather than etcd for round robin scheduling because etcd leases are not reliable enough to produce precise [round robin behavior][5]. +required | false +default | false +type | Boolean +example | {{< language-toggle >}} +{{< code yml >}} +enable_round_robin: true +{{< /code >}} +{{< code json >}} +{ + "enable_round_robin": true +} +{{< /code >}} +{{< /language-toggle >}} + +max_conn_lifetime | | +-------------|------ +description | Maximum time a connection can persist before being destroyed. Specify values with a numeral and a letter indicator: `s` to indicate seconds, `m` to indicate minutes, and `h` to indicate hours. For example, `1m`, `2h`, and `2h1m3s` are valid. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +max_conn_lifetime: 5m +{{< /code >}} +{{< code json >}} +{ + "max_conn_lifetime": "5m" +} +{{< /code >}} +{{< /language-toggle >}} + +max_idle_conns | | +-------------|------ +description | Maximum number of number of idle connections to retain. +required | false +default | `2` +type | Integer +example | {{< language-toggle >}} +{{< code yml >}} +max_idle_conns: 2 +{{< /code >}} +{{< code json >}} +{ + "max_idle_conns": 2 +} +{{< /code >}} +{{< /language-toggle >}} + +pool_size | | +-------------|------ +description | Maximum number of connections to hold in the PostgreSQL connection pool. We recommend `20` for most instances. +required | false +default | `0` (unlimited) +type | Integer +example | {{< language-toggle >}} +{{< code yml >}} +pool_size: 20 +{{< /code >}} +{{< code json >}} +{ + "pool_size": 20 +} +{{< /code >}} +{{< /language-toggle >}} + + + +strict | | +-------------|------ +description | If `true`, when the PostgresConfig resource is created, configuration validation will include connecting to the PostgreSQL database and executing a query to confirm whether the connected user has permission to create database tables. Otherwise, `false`.

    If `strict: true`, sensu-backend will try to connect to PostgreSQL indefinitely at 5-second intervals instead of reverting to etcd after 3 attempts.

    We recommend setting `strict: true` in most cases. If the connection fails or the user does not have permission to create database tables, resource configuration will fail and the configuration will not be persisted. This extended configuration is useful for debugging when you are not sure whether the configuration is correct or the database is working properly. +required | false +default | false +type | Boolean +example | {{< language-toggle >}} +{{< code yml >}} +strict: true +{{< /code >}} +{{< code json >}} +{ + "strict": true +} +{{< /code >}} +{{< /language-toggle >}} + + +[1]: ../../../sensuctl/#first-time-setup-and-authentication +[2]: ../../maintain-sensu/troubleshoot/ +[3]: https://aws.amazon.com/rds/ +[4]: https://pkg.go.dev/github.com/lib/pq@v1.2.0#hdr-Connection_String_Parameters +[5]: ../../../observability-pipeline/observe-schedule/checks/#round-robin-checks +[6]: ../deployment-architecture/ +[7]: https://etcd.io/docs/latest/op-guide/clustering/ +[8]: ../cluster-sensu/#use-an-external-etcd-cluster +[9]: ../../../web-ui/ +[10]: ../../../sensuctl/create-manage-resources/#manually-resolve-events +[11]: ../../../api/core/events/ +[12]: ../../../observability-pipeline/observe-process/populate-metrics-influxdb/ +[14]: https://www.postgresql.org +[15]: https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING +[16]: ../../../sensuctl/create-manage-resources/#create-resources +[17]: #spec-attributes +[18]: #datastore-specification +[19]: ../install-sensu/#ports +[20]: https://www.postgresql.org/docs/current/config-setting.html +[21]: https://www.postgresql.org/docs/current/libpq-envars.html +[22]: ../../../observability-pipeline/observe-schedule/backend/#environment-variables +[23]: https://www.postgresql.org/docs/current/libpq.html +[24]: #use-environment-variables-to-configure-postgresql diff --git a/content/sensu-go/6.12/operations/deploy-sensu/deployment-architecture.md b/content/sensu-go/6.12/operations/deploy-sensu/deployment-architecture.md new file mode 100644 index 0000000000..08fb657f1c --- /dev/null +++ b/content/sensu-go/6.12/operations/deploy-sensu/deployment-architecture.md @@ -0,0 +1,199 @@ +--- +title: "Deployment architecture for Sensu" +linkTitle: "Deployment Architecture" +description: "This guide describes considerations, potential architectures, and recommendations for a production-ready Sensu deployment." +weight: 30 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: deploy-sensu +--- + +This guide describes various planning considerations and recommendations for a production-ready Sensu deployment, including details related to communication security and common deployment architectures. + +etcd is a key-value store that is used by applications of varying complexity, from simple web apps to Kubernetes. +The Sensu backend uses an embedded etcd instance for storing both configuration and observability event data, so you can get Sensu up and running without external dependencies. + +By building atop etcd, Sensu's backend inherits a number of characteristics to consider when you're planning for a Sensu deployment. + +## Create and maintain clusters + +Sensu's embedded etcd supports initial cluster creation via a static list of peer URLs. +After you create a cluster, you can add and remove cluster members with etcdctl tooling. + +If you have a healthy clustered backend, you only need to make [Sensu API][2] calls to any one of the cluster members. +The cluster protocol will replicate your changes to all cluster members. + +Read [Run a Sensu cluster][7] and the [etcd documentation][4] for more information. + +## Hardware sizing + +Because etcd's design prioritizes consistency across a cluster, the speed with which write operations can be completed is very important to the Sensu cluster's performance and health. +This means that you should provision Sensu backend infrastructure to provide sustained input/output operations per second (IOPS) appropriate for the rate of observability events the system will be required to process. + +To maximize Sensu Go performance, we recommend that you: + * Follow our [recommended backend hardware configuration][1]. + * Implement [documented etcd system tuning practices][11]. + * [Benchmark your etcd storage volume][12] to establish baseline IOPS for your system. + * [Scale event storage using PostgreSQL][13] to reduce the overall volume of etcd transactions. + +## Communications security + +Whether you're using using a single Sensu backend or multiple Sensu backends in a cluster, communication with the backend's various network ports (web UI, HTTP API, WebSocket API, etcd client and peer) occurs in cleartext by default. +We recommend that you encrypt network communications via TLS, which requires planning and explicit configuration. + +### Plan TLS for etcd + +The URLs for each member of an etcd cluster are persisted to the database after initialization. +As a result, moving a cluster from cleartext to encrypted communications requires resetting the cluster, which destroys all configuration and event data in the database. +Therefore, we recommend planning for encryption before initiating a clustered Sensu backend deployment. + +{{% notice warning %}} +**WARNING**: Reconfiguring a Sensu cluster for TLS post-deployment will require resetting all etcd cluster members, resulting in the loss of all data. +{{% /notice %}} + +As described in [Secure Sensu][6], the backend uses a shared certificate and key for web UI and agent communications. +You can secure communications with etcd using the same certificate and key. +The certificate's Common Name (CN) or Subject Alternative Name (SAN) must include the network interfaces and DNS names that will point to those systems. + +{{% notice note %}} +**NOTE**: As of [Go 1.15](https://golang.google.cn/doc/go1.15#commonname), certificates must include their CN as an SAN field. +To prevent connection errors, follow [Generate certificates](../generate-certificates/) to make sure your certificates' SAN fields include their CNs. +{{% /notice %}} + +Read [Run a Sensu cluster][7] and the [etcd documentation][4] for more information about TLS setup and configuration, including a walkthrough for generating TLS certificates for your cluster. + +## Common Sensu architectures + +Depending on your infrastructure and the type of environments you'll be monitoring, you may use one or a combination of these architectures to best fit your needs. + +### Single backend (standalone) + +The single backend (standalone) with embedded etcd architecture requires minimal resources but provides no redundancy in the event of failure. + +{{< figure src="/images/go/deployment_architecture/single_backend_standalone_architecture.png" alt="Single Sensu Go backend or standalone architecture" link="/images/go/deployment_architecture/single_backend_standalone_architecture.png" target="_blank" >}} + + +*

    Single Sensu Go backend or standalone architecture

    * + +You can reconfigure a single backend as a member of a cluster, but this operation requires destroying the existing database. + +The single backend (standalone) architecture may be a good fit for small- to medium-sized deployments (such as monitoring a remote office or datacenter), deploying alongside individual auto-scaling groups, or deploying in various segments of a logical environment spanning multiple cloud providers. + +For example, in environments with unreliable WAN connectivity, having agents connect to a local backend may be more reliable than having agents connect over WAN or VPN tunnel to a backend running in a central location. + +### Clustered deployment for single availability zone + +To increase availability and replicate both configuration and data, join the embedded etcd databases of multiple Sensu backend instances together in a cluster. +Read [Run a Sensu cluster][7] for more information. + +{{< figure src="/images/go/deployment_architecture/clustered_single_availability_zone.png" alt="Clustered Sensu Go architecture for a single availability zone" link="/images/go/deployment_architecture/clustered_single_availability_zone.png" target="_blank" >}} + + +*

    Clustered Sensu Go architecture for a single availability zone

    * + +Clustering requires an odd number of backend instances. +Although larger clusters provide better fault tolerance, write performance suffers because data must be replicated across more machines. +The etcd maintainers recommend clusters of 3, 5, or 7 backends. +Read the [etcd documentation][4] for more information. + +### Clustered deployment for multiple availability zones + +Distributing infrastructure across multiple availability zones in a given region helps ensure continuous availability of customer infrastructure in the region if any one availability zone becomes unavailable. +With this in mind, you can deploy a Sensu cluster across multiple availability zones in a given region, configured to tolerate reasonable latency between those availability zones. + +{{< figure src="/images/go/deployment_architecture/clustered_multiple_availability_zones.png" alt="Clustered Sensu Go architecture for multiple availability zones" link="/images/go/deployment_architecture/clustered_multiple_availability_zones.png" target="_blank" >}} + + +*

    Clustered Sensu Go architecture for multiple availability zones

    * + +### Large-scale clustered deployment for multiple availability zones + +In a large-scale clustered Sensu Go deployment, you can use as many backends as you wish. +Use one etcd node per availiability zone, with a minimum of three etcd nodes and a maximum of five. +Three etcd nodes allow you to tolerate the loss of a single node with minimal effect on performance. +Five etcd nodes allow you to tolerate the loss of two nodes, but with a greater effect on performance. + +{{< figure src="/images/go/deployment_architecture/large_scale_clustered_multiple_availability_zones.png" alt="Large-scale clustered Sensu Go architecture for multiple availability zones" link="/images/go/deployment_architecture/large_scale_clustered_multiple_availability_zones.png" target="_blank" >}} + + +*

    Large-scale clustered Sensu Go architecture for multiple availability zones

    * + +#### Scaled cluster performance with PostgreSQL + +To achieve the high rate of event processing that many enterprises require, Sensu supports PostgreSQL event storage as a [commercial feature][9]. +Read the [datastore reference][8] to configure the Sensu backend to use PostgreSQL for event storage. + +{{< figure src="/images/go/deployment_architecture/clustered_postgresql.png" alt="Clustered Sensu Go architecture with PostgreSQL" link="/images/go/deployment_architecture/clustered_postgresql.png" target="_blank" >}} + + +*

    Clustered Sensu Go architecture with PostgreSQL event storage

    * + +In load testing, Sensu Go has proven capable of processing 36,000 events per second when using PostgreSQL as the event store. +Review the [sensu-perf project repository][10] for a detailed explanation of our testing methodology and results. + +### Large-scale cloud deployment for multiple regions + +In a large-scale cloud deployment for multiple regions, place all backends, etcd nodes, and event datastores in a single region. +The backends communicate with agents in other regions via WebSocket transport. +This configuration allows you to load-balance traffic between the backends in the main regions and the agents in other regions. + +{{% notice note %}} +**NOTE**: Do not use read replicas in a cloud deployment. +Sensu is write-heavy, and the brief, unavoidable replication delays will cause inconsistency between etcd data and PostgreSQL data. +{{% /notice %}} + +This diagram depicts an example architecture for a Google Cloud Platform (GCP) deployment, but you can reproduce this architecture with your preferred cloud provider: + +{{< figure src="/images/go/deployment_architecture/cloud_multiregion_arch.png" alt="Large-scale clustered Sensu Go architecture for multiple availability zones" link="/images/go/deployment_architecture/cloud_multiregion_arch.png" target="_blank" >}} + + +*

    Example Sensu Go architecture for multi-region cloud deployments

    * + +In this example, the load balancer translates traffic on port 80 to port 3000 so that users do not need to include `:3000` in the web UI URL. +API traffic is load-balanced to the backends as well. + +## Architecture considerations + +### Networking + +Clustered deployments benefit from a fast and reliable network. +Ideally, they should be co-located in the same network segment with as little latency as possible between all the nodes. +We do not recommend clustering backends across disparate subnets or WAN connections. + +Although 1GbE is sufficient for common deployments, larger deployments will benefit from 10GbE, which allows a shorter mean time to recovery. + +As the number of agents connected to a backend cluster grows, so will the amount of communication between members of the cluster required for data replication. +With this in mind, clusters with a thousand or more agents should use a discrete network interface for peer communication. + +### Load balancing + +Although you can configure each Sensu agent with the URLs for multiple backend instances, we recommend that you configure agents to connect to a load balancer. +This approach gives operators more control over agent connection distribution and makes it possible to replace members of the backend cluster without updates to agent configuration. + +Conversely, you cannot configure the sensuctl command line tool with multiple backend URLs. +Under normal conditions, sensuctl communications and browser access to the web UI should be routed via a load balancer. + +#### Load balancing algorithms + +If the load balancer uses round robin mode, when an agent comes online, the load balancer sends the agent's traffic to whichever backend is next in the pattern, regardless of load. +This can result in slow load balancing among backends, especially after restarting a backend. + +In least connection mode, the load balancer sends new agent traffic to the backend with the least traffic. +This helps to evenly distribute the load among backends more quickly. + + +[1]: ../hardware-requirements/#backend-recommended-configuration +[2]: ../../../api/ +[4]: https://etcd.io/docs/ +[5]: https://etcd.io/docs/current/op-guide/security/ +[6]: ../secure-sensu/ +[7]: ../cluster-sensu/ +[8]: ../datastore/ +[9]: ../../../commercial/ +[10]: https://github.com/sensu/sensu-perf +[11]: https://etcd.io/docs/latest/tuning/#disk +[12]: https://www.ibm.com/cloud/blog/using-fio-to-tell-whether-your-storage-is-fast-enough-for-etcd +[13]: ../datastore/#scale-event-storage diff --git a/content/sensu-go/6.12/operations/deploy-sensu/etcdreplicators.md b/content/sensu-go/6.12/operations/deploy-sensu/etcdreplicators.md new file mode 100644 index 0000000000..0a102d3448 --- /dev/null +++ b/content/sensu-go/6.12/operations/deploy-sensu/etcdreplicators.md @@ -0,0 +1,555 @@ +--- +title: "Etcd replicators reference" +linkTitle: "Etcd Replicators Reference" +reference_title: "Etcd replicators" +type: "reference" +description: "Read this reference to learn to use Sensu's etcd replicators to manage role-based access control resources in one place and mirror changes to follower clusters." +weight: 170 +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: deploy-sensu +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access the EtcdReplicator datatype in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} + +{{% notice note %}} +**NOTE**: EtcdReplicator is a datatype in the enterprise/federation/v1 API, which is only accessible for users who have a cluster role that permits access to replication resources. +{{% /notice %}} + +Etcd replicators allow you to manage [role-based access control (RBAC)][3] resources in one place and mirror the changes to follower clusters. +The API sets up etcd mirrors for one-way key replication. + +The EtcdReplicator datatype will not use a namespace because it applies cluster-wide. +Therefore, only cluster role RBAC bindings will apply to it. + +## Etcd replicator examples + +Use the following four examples for `Role`, `RoleBinding`, `ClusterRole`, and `ClusterRoleBinding` resources to create a full replication of [RBAC policy][3]. + +{{% notice note %}} +**NOTE**: If you do not specify a namespace when you create a replicator, all namespaces for a given resource are replicated. +{{% /notice %}} + +### `Role` resource example + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: EtcdReplicator +api_version: federation/v1 +metadata: + name: role_replicator +spec: + ca_cert: /path/to/ssl/trusted-certificate-authorities.pem + cert: /path/to/ssl/cert.pem + key: /path/to/ssl/key.pem + insecure: false + url: http://127.0.0.1:2379 + api_version: core/v2 + resource: Role + replication_interval_seconds: 30 +{{< /code >}} + +{{< code json >}} +{ + "type": "EtcdReplicator", + "api_version": "federation/v1", + "metadata": { + "name": "role_replicator" + }, + "spec": { + "ca_cert": "/path/to/ssl/trusted-certificate-authorities.pem", + "cert": "/path/to/ssl/cert.pem", + "key": "/path/to/ssl/key.pem", + "insecure": false, + "url": "http://127.0.0.1:2379", + "api_version": "core/v2", + "resource": "Role", + "replication_interval_seconds": 30 + } +} +{{< /code >}} + +{{< /language-toggle >}} + +### `RoleBinding` resource example + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: EtcdReplicator +api_version: federation/v1 +metadata: + name: rolebinding_replicator +spec: + ca_cert: /path/to/ssl/trusted-certificate-authorities.pem + cert: /path/to/ssl/cert.pem + key: /path/to/ssl/key.pem + insecure: false + url: http://127.0.0.1:2379 + api_version: core/v2 + resource: RoleBinding + replication_interval_seconds: 30 +{{< /code >}} + +{{< code json >}} +{ + "type": "EtcdReplicator", + "api_version": "federation/v1", + "metadata": { + "name": "rolebinding_replicator" + }, + "spec": { + "ca_cert": "/path/to/ssl/trusted-certificate-authorities.pem", + "cert": "/path/to/ssl/cert.pem", + "key": "/path/to/ssl/key.pem", + "insecure": false, + "url": "http://127.0.0.1:2379", + "api_version": "core/v2", + "resource": "RoleBinding", + "replication_interval_seconds": 30 + } +} +{{< /code >}} + +{{< /language-toggle >}} + +### `ClusterRole` resource example + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: EtcdReplicator +api_version: federation/v1 +metadata: + name: clusterrole_replicator +spec: + ca_cert: /path/to/ssl/trusted-certificate-authorities.pem + cert: /path/to/ssl/cert.pem + key: /path/to/ssl/key.pem + insecure: false + url: http://127.0.0.1:2379 + api_version: core/v2 + resource: ClusterRole + replication_interval_seconds: 30 +{{< /code >}} + +{{< code json >}} +{ + "type": "EtcdReplicator", + "api_version": "federation/v1", + "metadata": { + "name": "clusterrole_replicator" + }, + "spec": { + "ca_cert": "/path/to/ssl/trusted-certificate-authorities.pem", + "cert": "/path/to/ssl/cert.pem", + "key": "/path/to/ssl/key.pem", + "insecure": false, + "url": "http://127.0.0.1:2379", + "api_version": "core/v2", + "resource": "ClusterRole", + "replication_interval_seconds": 30 + } +} +{{< /code >}} + +{{< /language-toggle >}} + +### `ClusterRoleBinding` resource example + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: EtcdReplicator +api_version: federation/v1 +metadata: + name: clusterrolebinding_replicator +spec: + ca_cert: /path/to/ssl/trusted-certificate-authorities.pem + cert: /path/to/ssl/cert.pem + key: /path/to/ssl/key.pem + insecure: false + url: http://127.0.0.1:2379 + api_version: core/v2 + resource: Role + replication_interval_seconds: 30 +{{< /code >}} + +{{< code json >}} +{ + "type": "EtcdReplicator", + "api_version": "federation/v1", + "metadata": { + "name": "clusterrolebinding_replicator" + }, + "spec": { + "ca_cert": "/path/to/ssl/trusted-certificate-authorities.pem", + "cert": "/path/to/ssl/cert.pem", + "key": "/path/to/ssl/key.pem", + "insecure": false, + "url": "http://127.0.0.1:2379", + "api_version": "core/v2", + "resource": "ClusterRoleBinding", + "replication_interval_seconds": 30 + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Critical success factors for etcd replication + +Before you implement etcd replicators, review these details — they are critical to your success. + +**Bind your etcd listener to an external port that is *not* the default.** + +- Replication will not work if you bind your etcd listener to the default port. + +**Use only addresses that clients can route to for `etcd-client-advertise-urls`.** + +- If you use addresses that clients cannot route to for `etcd-client-advertise-urls`, replication may be inconsistent: it may work at first but then stop working later. + +**Put the certificate and key of the follower cluster in files that the leader can access.** + +- If the leader cannot access the follower cluster files that contain the certificate and key, replication will not work. + +**For self-signed certificates, supply the CA certificate in the replicator definition.** + +- If you have a self-signed certificate and you do not supply the CA certificate in the replicator definition, replication will not work. + +**If you're using insecure mode, use TLS mutual authentication.** + +- Never use insecure mode without TLS mutual authentication outside of a testbed. + +**Create a replicator for each resource type you want to replicate.** + +- Replicating `namespace` resources will **not** replicate the resources that belong to those namespaces. + +{{% notice warning %}} +**WARNING**: Make sure to confirm your configuration. +The server will accept incorrect EtcdReplicator definitions without sending a warning. +If your configuration is incorrect, replication will not work. +{{% /notice %}} + +## Create a replicator + +You can use [enterprise/federation/v1 API endpoints][2] directly or [`sensuctl create`][4] to create replicators. + +When you create or update a replicator, an entry is added to the store and a new replicator process will spin up. +The replicator process watches the keyspace of the resource to be replicated and replicates all keys to the specified cluster in a last-write-wins fashion. + +When the cluster starts up, each sensu-backend scans the stored replicator definitions and starts a replicator process for each replicator definition. +Source clusters with more than one sensu-backend will cause redundant writes. +This is harmless, but you should consider it when designing a replicated system. + +{{% notice note %}} +**NOTE**: Create a replicator for each resource type you want to replicate. +Replicating `namespace` resources will **not** replicate the resources that belong to those namespaces. +{{% /notice %}} + +## Delete a replicator + +When you delete a replicator, the replicator will issue delete events to the remote cluster for all of the keys in its prefix. +It will not issue a delete of the entire key prefix (just in case the prefix is shared by keys that are local to the remote cluster). + +Rather than altering an existing replicator's connection details, delete and recreate the replicator with the new connection details. + +## Replicator configuration + +Etcd replicators are etcd key space replicators. +Replicators contain configuration for forwarding a set of keys from one etcd cluster to another. +Replicators are configured by specifying the TLS details of the remote cluster, its URL, and a resource type. + +## Etcd replicator specification + +### Top-level attributes + +api_version | | +-------------|------ +description | Top-level attribute that specifies the Sensu API version of the etcd-replicators API. Always `federation/v1`. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +api_version: federation/v1 +{{< /code >}} +{{< code json >}} +{ + "api_version": "federation/v1" +} +{{< /code >}} +{{< /language-toggle >}} + +metadata | | +-------------|------ +description | Top-level scope that contains the replicator `name` and `created_by` value. Namespace is not supported in the metadata because etcd replicators are cluster-wide resources. +required | true +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +metadata: + name: my_replicator + created_by: admin +{{< /code >}} +{{< code json >}} +{ + "metadata": { + "name": "my_replicator", + "created_by": "admin" + } +} +{{< /code >}} +{{< /language-toggle >}} + +spec | | +-------------|------ +description | Top-level map that includes the replicator [spec attributes][6]. +required | true +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +spec: + ca_cert: /path/to/ssl/trusted-certificate-authorities.pem + cert: /path/to/ssl/cert.pem + key: /path/to/ssl/key.pem + insecure: false + url: http://127.0.0.1:2379 + api_version: core/v2 + resource: Role + replication_interval_seconds: 30 +{{< /code >}} +{{< code json >}} +{ + "spec": { + "ca_cert": "/path/to/ssl/trusted-certificate-authorities.pem", + "cert": "/path/to/ssl/cert.pem", + "key": "/path/to/ssl/key.pem", + "insecure": false, + "url": "http://127.0.0.1:2379", + "api_version": "core/v2", + "resource": "Role", + "replication_interval_seconds": 30 + } +} +{{< /code >}} +{{< /language-toggle >}} + +type | | +-------------|------ +description | Top-level attribute that specifies the [`sensuctl create`][4] resource type. Always `EtcdReplicator.` +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +type: EtcdReplicator +{{< /code >}} +{{< code json >}} +{ + "type": "EtcdReplicator" +} +{{< /code >}} +{{< /language-toggle >}} + +### Metadata attributes + +| created_by | | +-------------|------ +description | Username of the Sensu user who created the replicator or last updated the replicator. Sensu automatically populates the `created_by` field when the replicator is created or updated. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +created_by: admin +{{< /code >}} +{{< code json >}} +{ + "created_by": "admin" +} +{{< /code >}} +{{< /language-toggle >}} + +name | | +-------------|------ +description | Replicator name used internally by Sensu. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +name: my_replicator +{{< /code >}} +{{< code json >}} +{ + "name": "my_replicator" +} +{{< /code >}} +{{< /language-toggle >}} + +### Spec attributes + +api_version | | +-------------|------- +description | Sensu API version of the resource to replicate. +required | false +type | String +default | `core/v2` +example | {{< language-toggle >}} +{{< code yml >}} +api_version: core/v2 +{{< /code >}} +{{< code json >}} +{ + "api_version": "core/v2" +} +{{< /code >}} +{{< /language-toggle >}} + +ca_cert | | +-------------|------ +description | Path to the PEM-format CA certificate to use for TLS client authentication. +required | true if `insecure: false` (the default configuration). If `insecure: true`, `ca_cert` is not required. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +ca_cert: /path/to/trusted-certificate-authorities.pem +{{< /code >}} +{{< code json >}} +{ + "ca_cert": "/path/to/trusted-certificate-authorities.pem" +} +{{< /code >}} +{{< /language-toggle >}} + +cert | | +-------------|------ +description | Path to the PEM-format certificate to use for TLS client authentication. This certificate is required for secure client communication. +required | true if `insecure: false` (the default configuration). If `insecure: true`, `cert` is not required. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +cert: /path/to/ssl/cert.pem +{{< /code >}} +{{< code json >}} +{ + "cert": "/path/to/ssl/cert.pem" +} +{{< /code >}} +{{< /language-toggle >}} + +insecure | | +-------------|------- +description | `true` to disable transport security. Otherwise, `false`. {{% notice warning %}} +**WARNING**: Disable transport security with care. +{{% /notice %}} +required | false +type | Boolean +default | `false` +example | {{< language-toggle >}} +{{< code yml >}} +insecure: false +{{< /code >}} +{{< code json >}} +{ + "insecure": false +} +{{< /code >}} +{{< /language-toggle >}} + +key | | +-------------|------ +description | Path to the PEM-format key file associated with the `cert` to use for TLS client authentication. This key and its corresponding certificate are required for secure client communication. +required | true if `insecure: false` (the default configuration). If `insecure: true`, `key` is not required. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +key: /path/to/ssl/key.pem +{{< /code >}} +{{< code json >}} +{ + "key": "/path/to/ssl/key.pem" +} +{{< /code >}} +{{< /language-toggle >}} + + + +namespace | | +-------------|------- +description | Namespace to constrain replication to. If you do not include `namespace`, all namespaces for a given resource are replicated. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +namespace: default +{{< /code >}} +{{< code json >}} +{ + "namespace": "default" +} +{{< /code >}} +{{< /language-toggle >}} + +replication_interval_seconds | | +----------------------------------|------- +description | Interval at which the resource will be replicated. In seconds. +required | false +type | Integer +default | 30 +example | {{< language-toggle >}} +{{< code yml >}} +replication_interval_seconds: 30 +{{< /code >}} +{{< code json >}} +{ + "replication_interval_seconds": 30 +} +{{< /code >}} +{{< /language-toggle >}} + +resource | | +-------------|------- +description | Name of the resource to replicate. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +resource: Role +{{< /code >}} +{{< code json >}} +{ + "resource": "Role" +} +{{< /code >}} +{{< /language-toggle >}} + +url | | +-------------|------- +description | Destination cluster URL. If specifying more than one, use a comma to separate. Replace with a non-default value for secure client communication. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +url: http://127.0.0.1:2379 +{{< /code >}} +{{< code json >}} +{ + "url": "http://127.0.0.1:2379" +} +{{< /code >}} +{{< /language-toggle >}} + + +[2]: ../../../api/enterprise/federation/ +[3]: ../../control-access/rbac/ +[4]: ../../../sensuctl/create-manage-resources/#create-resources +[5]: ../secure-sensu/#create-self-signed-certificates-for-securing-etcd-and-backend-agent-communication +[6]: #spec-attributes diff --git a/content/sensu-go/6.12/operations/deploy-sensu/generate-certificates.md b/content/sensu-go/6.12/operations/deploy-sensu/generate-certificates.md new file mode 100644 index 0000000000..a5ba768a17 --- /dev/null +++ b/content/sensu-go/6.12/operations/deploy-sensu/generate-certificates.md @@ -0,0 +1,481 @@ +--- +title: "Generate certificates for your Sensu installation" +linkTitle: "Generate Certificates" +guide_title: "Generate certificates for your Sensu installation" +type: "guide" +description: "After you install Sensu, learn how to secure it with public key infrastructure (PKI). Set up PKI and generate the certificates you need to secure Sensu." +weight: 50 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: deploy-sensu +--- + +This guide explains how to generate the certificates you need to secure a Sensu cluster and its agents. + +When deploying Sensu for use outside of a local development environment, you should secure it using transport layer security (TLS). +TLS uses encryption to provide security for communication between Sensu backends and agents as well as communication between human operators and the Sensu backend, such as web UI or sensuctl access. + +Because reconfiguring an existing Sensu deployment from cleartext to TLS can be time-consuming, we recommend that you configure TLS for your backend from the very beginning. + +TLS is also required to use some of Sensu's commercial features, like [secrets management][9] and [mutual TLS authentication (mTLS)][5]. + +## Prerequisites + +To use this guide, you must have already [installed Sensu][10] on: + +- One backend system or three backend systems that you plan to cluster together. +- One or more agents. + +## Public key infrastructure (PKI) + +To use TLS, you must either possess existing [public key infrastructure (PKI)][8] or generate your own Certificate Authority (CA) for issuing certificates. + +This guide describes how to set up a minimal CA and generate the certificates you need to secure Sensu communications for a clustered backend and agents. + +If your organization has existing PKI for certificate issuance, you can adapt the suggestions in this guide to your organization's PKI. +Recommended practices for deploying and maintaining production PKI can be complex and case-specific, so they are not included in the scope of this guide. + +## Issue certificates + +Use a CA certificate and key to generate certificates and keys to use with Sensu backends and agents. + +This guide uses the [CloudFlare cfssl][6] toolkit to generate a CA and self-signed certificates from that CA. +The examples assume that you'll install the certificates and keys in the `/etc/sensu/tls` directory. + +### Install TLS + +The [CloudFlare cfssl][6] toolkit is released as a collection of command-line tools. + +These tools only need to be installed on one system to generate your CA and issue certificates. + +You may install the toolkit on your laptop or workstation and store the files there for safekeeping or install the toolkit on one of the systems where you'll run the Sensu backend. +The example in this guide installs cfssl on a Linux system. + +1. Download the cfssl executable: +{{< code shell >}} +sudo curl -L https://github.com/cloudflare/cfssl/releases/download/v1.4.1/cfssl_1.4.1_linux_amd64 -o /usr/local/bin/cfssl +{{< /code >}} + +2. Download the cfssljson executable: +{{< code shell >}} +sudo curl -L https://github.com/cloudflare/cfssl/releases/download/v1.4.1/cfssljson_1.4.1_linux_amd64 -o /usr/local/bin/cfssljson +{{< /code >}} + +3. Install the cfssl and cfssljson executables in /usr/local/bin: +{{< code shell >}} +sudo chmod +x /usr/local/bin/cfssl* +{{< /code >}} + +4. Verify the cfssl executable is version 1.4.1 and runtime go1.12.12: +{{< code shell >}} +cfssl version +{{< /code >}} + +5. Verify the cfssljson executable is version 1.4.1 and runtime go1.12.12: +{{< code shell >}} +cfssljson -version +{{< /code >}} + +### Create a Certificate Authority (CA) + +Follow these steps to create a CA with cfssl and cfssljson: + +1. Create `/etc/sensu/tls` (which does not exist by default): +{{< code shell >}} +mkdir -p /etc/sensu/tls +{{< /code >}} + +2. Navigate to the new `/etc/sensu/tls` directory: +{{< code shell >}} +cd /etc/sensu/tls +{{< /code >}} + +3. Create the CA: +{{< code shell >}} +echo '{"CN":"Sensu Test CA","key":{"algo":"rsa","size":2048}}' | cfssl gencert -initca - | cfssljson -bare ca - +{{< /code >}} + +4. Define signing parameters and profiles (the agent profile provides the "client auth" usage required for mTLS): +{{< code shell >}} +echo '{"signing":{"default":{"expiry":"17520h","usages":["signing","key encipherment","client auth"]},"profiles":{"backend":{"usages":["signing","key encipherment","server auth","client auth"],"expiry":"4320h"},"agent":{"usages":["signing","key encipherment","client auth"],"expiry":"4320h"}}}}' > ca-config.json +{{< /code >}} +{{% notice note %}} +**NOTE**: We suggest a 6-month expiry duration for security, but you can use any duration you prefer when you define the `expiry` attribute value in the signing parameters. +{{% /notice %}} + + + +You should now have a directory at `/etc/sensu/tls` that contains the following files: + + filename | description | +-----------------|-------------| +`ca.pem` | CA root certificate. Required for all systems running the Sensu backend or agent. The agent and backend use `ca.pem` to validate server certificates at connection time. | +`ca-key.pem` | CA root certificate private key. | +`ca-config.json` | CA signing parameters and profiles. Not used by Sensu. | +`ca.csr` | Certificate signing request for the CA root certificate. Not used by Sensu. | + + +### Generate backend cluster certificates + +Now that you've generated a CA, you will use it to generate certificates and keys for each backend server (etcd peer). + +For each backend server, document the IP addresses and hostnames to use in backend and agent communications. +During initial configuration of a cluster of Sensu backends, you must describe every member of the cluster with a URL passed as the value of the `etcd-initial-cluster` parameter. + +In issuing certificates for cluster members, the IP address or hostname used in these URLs must be represented in either the Common Name (CN) or Subject Alternative Name (SAN) records in the certificate. + +{{% notice note %}} +**NOTE**: As of [Go 1.15](https://golang.google.cn/doc/go1.15#commonname), certificates must include their CN as an SAN field. +Follow the instructions in this guide to make sure your certificates' SAN fields include their CNs. +{{% /notice %}} + + + +This guide assumes a scenario with three backend members that are reachable via a `10.0.0.x` IP address, a fully qualified name (for example, `backend-1.example.com`), and an unqualified name (for example, `backend-1`): + +Unqualified
    name | IP address | Fully qualified
    domain name
    (FQDN) | Additional
    names | +-----------------|------------|------------------------------------|----------------------| +backend-1 | 10.0.0.1 | backend-1.example.com | localhost, 127.0.0.1 | +backend-2 | 10.0.0.2 | backend-2.example.com | localhost, 127.0.0.1 | +backend-3 | 10.0.0.3 | backend-3.example.com | localhost, 127.0.0.1 | + +The additional names for localhost and 127.0.0.1 are added here for convenience and are not strictly required. + +Use these name and address details to create two `*.pem` files and one `*.csr` file for each backend. + +- The values provided for the ADDRESS variable will be used to populate the certificate's SAN records. +For systems with multiple hostnames and IP addresses, add each to the comma-delimited value of the ADDRESS variable. +- The value provided for the NAME variable will be used to populate the certificate's CN record. +It will also be used in the names for the `*.pem` and `*.csr` files. + +For example, to create certificate and key files for the [three backends][18]: + +**backend-1** + +{{< code shell >}} +export ADDRESS=localhost,127.0.0.1,10.0.0.1,backend-1 +export NAME=backend-1.example.com +echo '{"CN":"'$NAME'","hosts":[""],"key":{"algo":"rsa","size":2048}}' | cfssl gencert -config=ca-config.json -profile="backend" -ca=ca.pem -ca-key=ca-key.pem -hostname="$ADDRESS" - | cfssljson -bare $NAME +{{< /code >}} + +**backend-2** + +{{< code shell >}} +export ADDRESS=localhost,127.0.0.1,10.0.0.2,backend-2 +export NAME=backend-2.example.com +echo '{"CN":"'$NAME'","hosts":[""],"key":{"algo":"rsa","size":2048}}' | cfssl gencert -config=ca-config.json -profile="backend" -ca=ca.pem -ca-key=ca-key.pem -hostname="$ADDRESS" - | cfssljson -bare $NAME +{{< /code >}} + +**backend-3** + +{{< code shell >}} +export ADDRESS=localhost,127.0.0.1,10.0.0.3,backend-3 +export NAME=backend-3.example.com +echo '{"CN":"'$NAME'","hosts":[""],"key":{"algo":"rsa","size":2048}}' | cfssl gencert -config=ca-config.json -profile="backend" -ca=ca.pem -ca-key=ca-key.pem -hostname="$ADDRESS" - | cfssljson -bare $NAME +{{< /code >}} + + + +The `/etc/sensu/tls` directory should now include three files for each backend, in addition to the [four original CA files][11]: + +filename | description | required on backend?| +-----------------------|------------------------------|---------------------| +`backend-*.pem` | Backend server certificate | {{< check >}} | +`backend-*-key.pem` | Backend server private key | {{< check >}} | +`backend-*.csr` | Certificate signing request | | + +In our example with [three backends][18], the directory listing for `/etc/sensu/tls` would include 13 files: + +{{< code text >}} +/etc/sensu/tls/ +├── backend-1-key.example.com.pem +├── backend-1.example.com.pem +├── backend-1.example.com.csr +├── backend-2-key.example.com.pem +├── backend-2.example.com.pem +├── backend-2.example.com.csr +├── backend-3-key.example.com.pem +├── backend-3.example.com.pem +├── backend-3.example.com.csr +├── ca.pem +├── ca-key.pem +├── ca-config.json +└── ca.csr +{{< /code >}} + +{{% notice warning %}} +**WARNING**: If you are **not** setting up [agent mTLS authentication](../secure-sensu/#optional-configure-sensu-agent-mtls-authentication), delete the `ca-key.pem` file from the `/etc/sensu/tls` directory. +The `ca-key.pem` file contains sensitive information and is no longer needed unless you are setting up agent mTLS authentication. +{{% /notice %}} + +To make sure the backend files in `/etc/sensu/tls` are accessible only by the `sensu` user, run: + +{{< code shell >}} +chown sensu /etc/sensu/tls/*.pem +{{< /code >}} + +And: + +{{< code shell >}} +chmod 400 /etc/sensu/tls/*.pem +{{< /code >}} + +### Generate agent certificate + +{{% notice note %}} +**NOTE**: Agent certificates are only required for [agent mTLS authentication](../secure-sensu/#optional-configure-sensu-agent-mtls-authentication). +If you are not configuring mTLS for Sensu agents, you do not need to generate agent certificates. +{{% /notice %}} + +Now you will generate a certificate that agents can use to connect to the Sensu backend. +Sensu's commercial distribution offers support for authenticating agents via TLS certificates instead of a username and password. + +For this certificate, you only need to specify a CN (here, `agent`) — you don't need to specify an address. +You will create the files `agent.pem`, `agent-key.pem`, and `agent.csr`: + +{{< code shell >}} +export NAME=agent +echo '{"CN":"'$NAME'","hosts":[""],"key":{"algo":"rsa","size":2048}}' | cfssl gencert -config=ca-config.json -ca=ca.pem -ca-key=ca-key.pem -hostname="" -profile=agent - | cfssljson -bare $NAME +{{< /code >}} + + + +The `/etc/sensu/tls` directory should now include a set of files for use by Sensu agents: + +filename | description | required on agent? | +-------------------|------------------------------|---------------------| +`agent.pem` | Agent certificate | {{< check >}} | +`agent-key.pem` | Agent private key | {{< check >}} | +`agent.csr` | Certificate signing request | | + +{{% notice warning %}} +**WARNING**: Before you continue, delete the `ca-key.pem` file from the `/etc/sensu/tls` directory. +This file contains sensitive information and is no longer needed. +{{% /notice %}} + +To continue the example with [three backends][18], the directory listing for `/etc/sensu/tls` will include 15 files after deleting the `ca-key.pem` file: + +{{< code text >}} +/etc/sensu/tls/ +├── agent-key.pem +├── agent.pem +├── agent.csr +├── backend-1-key.example.com.pem +├── backend-1.example.com.pem +├── backend-1.example.com.csr +├── backend-2-key.example.com.pem +├── backend-2.example.com.pem +├── backend-2.example.com.csr +├── backend-3-key.example.com.pem +├── backend-3.example.com.pem +├── backend-3.example.com.csr +├── ca.pem +├── ca-config.json +└── ca.csr +{{< /code >}} + +To make sure the agent `/etc/sensu/tls` files are accessible only by the `sensu` user, run: + +{{< code shell >}} +chown sensu /etc/sensu/tls/*.pem +{{< /code >}} + +And: + +{{< code shell >}} +chmod 400 /etc/sensu/tls/*.pem +{{< /code >}} + +## Install CA certificates + +Before you install the CA certificates, **make sure that the `/etc/sensu/tls` directory does not contain the `ca-key.pem` file**. +The `ca-key.pem` file contains sensitive information that is no longer needed, so you should delete it. + +Also, make sure that `/etc/sensu/tls` includes the [CA root certificate and key][11], as well as a certificate and key for each [backend][12] and [agent][13] you are securing. + +We recommend installing the CA root certificate in the trust store of both your Sensu systems and those systems used by operators to manage Sensu. +Installing the CA certificate in the trust store for these systems makes it easier to connect via web UI or sensuctl without being prompted to accept certificates signed by your self-generated CA. + +{{< language-toggle >}} +{{< code shell "Debian family" >}} +chmod 644 /etc/sensu/tls/ca.pem +chown root /etc/sensu/tls/ca.pem +sudo apt-get install ca-certificates -y +sudo ln -sfv /etc/sensu/tls/ca.pem /usr/local/share/ca-certificates/sensu-ca.crt +sudo update-ca-certificates +{{< /code >}} + +{{< code shell "RHEL family" >}} +chmod 644 /etc/sensu/tls/ca.pem +chown root /etc/sensu/tls/ca.pem +sudo yum install -y ca-certificates +sudo update-ca-trust force-enable +sudo ln -s /etc/sensu/tls/ca.pem /etc/pki/ca-trust/source/anchors/sensu-ca.pem +sudo update-ca-trust +{{< /code >}} + +{{< code shell "macOS" >}} +Import the root CA certificate on the Mac. +Double-click the root CA certificate to open it in Keychain Access. +The root CA certificate appears in login. +Copy the root CA certificate to System to ensure that it is trusted by all users and local system processes. +Open the root CA certificate, expand Trust, select Use System Defaults, and save your changes. +Reopen the root CA certificate, expand Trust, select Always Trust, and save your changes. +Delete the root CA certificate from login. +{{< /code >}} + +{{< code shell "Windows" >}} +Press Windows+R to open the Run dialog. +Type "MMC" (without quotation marks) in the Run dialog and press Enter to open the MMC console. +In the MMC console, expand the Certificates (Local Computer) node and navigate to Trusted Root Certification Authorities > Certificates. +Right-click the Trusted Root Certification Authorities > Certificates folder and select All Tasks > Import to open the Certificate Import dialog. +In the Certificate Import dialog, click Next and browse to the location where the root CA certificate is stored. +Select the root CA certificate file and click Open. +Click Next, click Next, and click Finish. +{{< /code >}} + +{{< /language-toggle >}} + +## Renew self-generated certificates + +To keep your Sensu deployment running smoothly, renew your self-generated certificates before they expire. +Depending on how your certificates are configured, one backend certificate may expire before the others or all three backend certificates may expire at the same time. +The agent certificate also expires. + +This section explains how to find certificate expiration dates, confirm whether certificates have already expired, and renew certificates. + +### Find certificate expiration dates + +Use this check to find certificate expiration dates so you can renew certificates before they expire and avoid observability interruptions. + +Before you run the check, replace `.pem` in the command with the name of the certificate you want to check (for example, `backend-1.example.com.pem`). + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: expired_certs +spec: + command: openssl x509 -noout -enddate -in .pem + subscriptions: + - system + publish: true +{{< /code >}} + +{{< code json >}} +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "expired_certs" + }, + "spec": { + "command": "openssl x509 -noout -enddate -in .pem", + "subscriptions": [ + "system" + ], + "publish": true + } +} +{{< /code >}} + +{{< /language-toggle >}} + +The check output will be in the format `notAfter=Month Day HH:MM:SS Year Timezone`. +For example: + +{{< code text >}} +notAfter=Jul 3 22:23:50 2021 GMT +{{< /code >}} + +Add a [handler][17] to send the check output as a notification or to a log file. + +### Identify expired certificates + +The following `sensuctl cluster health` response indicates that one backend certificate is expired: + +{{< code text >}} +Error: GET "/health": Get https://localhost:8080/health?timeout=3: x509: certificate has expired or is not yet valid +{{< /code >}} + +The log for the expired backend will be similar to this example: + +{{< code text >}} +backend-1.example.com | {"component":"etcd","level":"warning","msg":"health check for peer a95ca1cdb0b1fcc3 could not connect: remote error: tls: bad certificate (prober \"ROUND_TRIPPER_RAFT_MESSAGE\")","pkg":"rafthttp","time":"2021-06-22T20:40:54Z"} +backend-1.example.com | {"component":"etcd","level":"warning","msg":"health check for peer a95ca1cdb0b1fcc3 could not connect: remote error: tls: bad certificate (prober \"ROUND_TRIPPER_RAFT_MESSAGE\")","pkg":"rafthttp","time":"2021-06-22T20:40:54Z"} +{{< /code >}} + +If you restart the cluster with one expired backend certificate, the `sensuctl cluster health` response will include an error: + +{{< code text >}} +Error: GET "/health": failed to request new refresh token; client returned 'Post https://localhost:8080/auth/token: EOF' +{{< /code >}} + +When all three backend certificates are expired, the log will be similar to this example: + +{{< code text >}} +backend-1.example.com | {"component":"etcd","level":"warning","msg":"health check for peer a95ca1cdb0b1fcc3 could not connect: x509: certificate has expired or is not yet valid (prober \"ROUND_TRIPPER_RAFT_MESSAGE\")","pkg":"rafthttp","time":"2021-06-25T17:49:53Z"} +backend-2.example.com | {"component":"etcd","level":"warning","msg":"health check for peer 4cc36e198efb22e8 could not connect: x509: certificate has expired or is not yet valid (prober \"ROUND_TRIPPER_RAFT_MESSAGE\")","pkg":"rafthttp","time":"2021-06-25T17:49:16Z"} +backend-3.example.com | {"component":"etcd","level":"warning","msg":"health check for peer 8425a7b2d2ee8597 could not connect: x509: certificate has expired or is not yet valid (prober \"ROUND_TRIPPER_RAFT_MESSAGE\")","pkg":"rafthttp","time":"2021-06-25T17:49:16Z"} +{{< /code >}} + +If you restart the cluster with three expired backend certificates, the `sensuctl cluster health` response will include an error: + +{{< code text >}} +Error: GET "/health": Get https://127.0.0.1:8080/health?timeout=3: EOF +{{< /code >}} + +The following `sensuctl cluster health` response helps confirm that all three backend certificates are expired, together with the log warning and restart error examples: + +{{< code text >}} +=== Etcd Cluster ID: 45c04eab9efc0d11 + ID Name Error Healthy + ────────────────── ──────────────────────── ─────────────────────────── ───────── + a95ca1cdb0b1fcc3 backend-1.example.com context deadline exceeded false + 8425a7b2d2ee8597 backend-2.example.com context deadline exceeded false + 4cc36e198efb22e8 backend-3.example.com context deadline exceeded false +{{< /code >}} + +An expired agent certificate does not cause any errors or log messages to indicate the expiration. +Use the [certificate expiration check][16] to find the agent certificate expiration date. + +### Renew certificates + +To renew your certificates, whether they expired or not, follow the steps to [create a CA][7], [generate backend certificates][14], or [generate an agent certificate][15]. +The new certificate will override the existing certificate. + +After you save the new certificates, restart each backend: + +{{< code shell >}} +sudo systemctl start sensu-backend +{{< /code >}} + +## Next step: Secure Sensu + +Now that you have generated the required certificates, follow [Secure Sensu][1] to make your Sensu installation production-ready. + + +[1]: ../secure-sensu/ +[2]: ../secure-sensu/#secure-etcd-peer-communication +[3]: ../secure-sensu/#secure-the-sensu-agent-api-http-api-and-web-ui +[4]: ../secure-sensu/#secure-sensu-agent-to-server-communication +[5]: ../secure-sensu/#configure-sensu-agent-mtls-authentication +[6]: https://github.com/cloudflare/cfssl +[7]: #create-a-certificate-authority-ca +[8]: https://en.wikipedia.org/wiki/Public_key_infrastructure +[9]: ../../manage-secrets/secrets-management/ +[10]: ../../deploy-sensu/install-sensu/ +[11]: #copy-ca-pem +[12]: #copy-backend-pem +[13]: #copy-agent-pem +[14]: #generate-backend-cluster-certificates +[15]: #generate-agent-certificate +[16]: #find-certificate-expiration-dates +[17]: ../../../observability-pipeline/observe-process/handlers/ +[18]: #example-backends diff --git a/content/sensu-go/6.12/operations/deploy-sensu/hardware-requirements.md b/content/sensu-go/6.12/operations/deploy-sensu/hardware-requirements.md new file mode 100644 index 0000000000..cf73907d49 --- /dev/null +++ b/content/sensu-go/6.12/operations/deploy-sensu/hardware-requirements.md @@ -0,0 +1,133 @@ +--- +title: "Hardware requirements" +linkTitle: "Hardware Requirements" +description: "Plan your Sensu deployment with information about hardware and networking requirements for running Sensu backends and agents on your infrastructure." +weight: 10 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: deploy-sensu +--- + +## Sensu backend requirements + +### Backend minimum requirements + +This configuration is the minimum required to run the Sensu [backend][9] (although it is insufficient for production use): + +- 64-bit Intel or AMD CPU +- 4 GB RAM +- 4 GB free disk space +- 10 mbps network link + +Review the [backend recommended configuration][2] for production recommendations. + +### Backend recommended configuration + +This backend configuration is recommended as a baseline for production use to ensure a good user and operator experience: + +- 64-bit four-core Intel or AMD CPU +- 8 GB RAM +- SSD [non-volatile memory express (NVMe) or serial advanced technology attachment 3 (SATA3)] +- Gigabit ethernet + +Using additional resources (and even over-provisioning) further improves stability and scalability. + +The Sensu backend is typically CPU- and storage-intensive. +In general, the backend's use of these resources scales linearly with the total number of checks executed by all Sensu agents connecting to the backend. + +The Sensu backend is a massively parallel application that can scale to any number of CPU cores. +Provision approximately one CPU core for every 50 checks per second (including agent keepalives). +For most installations, four CPU cores are sufficient. +Larger installations may find that more CPU cores (8+) are necessary. + +Every executed Sensu check results in storage writes. +When provisioning storage, a good guideline is to have twice as many **sustained disk input/output operations per second (IOPS)** as you expect to have events per second. + +Don't forget to include agent keepalives in your calculation. +Each agent publishes a keepalive every 20 seconds. +For example, in a cluster of 100 agents, you can expect the agents to consume 10 write IOPS for keepalives. + +The Sensu backend uses a relatively modest amount of RAM in most circumstances. +Larger production deployments use more RAM (8+ GB). + +## Sensu agent requirements + +### Agent minimum requirements + +This configuration is the minimum required to run the Sensu [agent][10] (although it is insufficient for production use): + +- 386, amd64, ARMv5, or MIPS CPU +- 128 MB RAM +- 10 mbps network link + +Review the [agent recommended configuration][3] for production recommendations. + +### Agent recommended configuration + +This agent configuration is recommended as a baseline for production use to ensure a good user and operator experience: + +- 64-bit four-core Intel or AMD CPU +- 512 MB RAM +- Gigabit ethernet + +The Sensu agent itself is lightweight and should be able to run on all but the most modest hardware. +However, because the agent is responsible for executing checks, you should factor the agent's responsibilities into your hardware provisioning. + +## Networking recommendations + +Sensu uses WebSockets for communication between the agent and backend. +All communication occurs over a single TCP socket. + +We recommend that you connect backends and agents via gigabit ethernet, but any reliable network link should work (for example, WiFi and 4G). +If the backend logs include WebSocket timeouts, you may need to use a more reliable network link between the backend and agents. + +## Cloud recommendations + +For all cloud providers, we recommend using local NVMe SSDs for storage and deploying all Sensu backends and etcd instances in the same region. + +Sensu is compatible with all cloud provider database instances. +We recommend using PostgreSQL with high availability for the event store. + +{{% notice note %}} +**NOTE**: Sensu does not require a particular CPU manufacturer for cloud storage. +{{% /notice %}} + +### Amazon EC2 + +For Sensu backends or etcd nodes, the recommended Amazon EC2 instance type and size is **M5d.xlarge**. +The [M5d.xlarge instance][1] provides four vCPU, 16 GB of RAM, up to 10 gbps network connectivity, and a 150-GB NVMe SSD directly attached to the instance host, which is optimal for sustained disk IOPS. + +### Microsoft Azure + +Use the **D4ds v4** Microsoft Azure virtual machine for Sensu backends or etcd nodes. +The [D4ds v4 virtual machine][6] provides four vCPU, 16 GB of RAM, and a 150-GB SSD directly attached to the instance host (optimal for sustained disk IOPS). + +### Digital Ocean + +Use Digital Ocean [Storage-Optimized Droplets][5] for Sensu backends or etcd. +The minimum [Storage-Optimized Droplet plan][4] provides two vCPU, 16 GB of RAM, and a 300-GB NVMe SSD. +Storage is directly attached to the hypervisor rather than connected via network. + +### Google Cloud + +For Sensu backends or etcd nodes, the recommended Google Cloud Compute Engine type and size is **n2-standard-4**, with SSD provisioned space. +The [n2-standard-4][7] compute engine provides four vCPU, 16 GB of RAM, and up to 10 gbps network connectivity. + +Google Cloud offers disk space separately, and we recommend at least 150 GB of [SSD provisioned space][8] for Sensu backends running embedded etcd. + +You can use Google Cloud's regional managed instance groups (MIGs) to deploy Sensu backends and etcd instances. + + +[1]: https://aws.amazon.com/ec2/instance-types/m5/ +[2]: #backend-recommended-configuration +[3]: #agent-recommended-configuration +[4]: https://www.digitalocean.com/pricing +[5]: https://docs.digitalocean.com/products/droplets/resources/choose-plan/#dedicated-cpu-storage-optimized-droplet +[6]: https://docs.microsoft.com/en-us/azure/virtual-machines/ddv4-ddsv4-series +[7]: https://cloud.google.com/compute/docs/general-purpose-machines#n2_machines +[8]: https://cloud.google.com/compute/disks-image-pricing#disk +[9]: ../../../observability-pipeline/observe-schedule/backend/ +[10]: ../../../observability-pipeline/observe-schedule/agent/ diff --git a/content/sensu-go/6.12/operations/deploy-sensu/install-sensu.md b/content/sensu-go/6.12/operations/deploy-sensu/install-sensu.md new file mode 100644 index 0000000000..c77d733ea8 --- /dev/null +++ b/content/sensu-go/6.12/operations/deploy-sensu/install-sensu.md @@ -0,0 +1,599 @@ +--- +title: "Install Sensu" +linkTitle: "Install Sensu" +description: "Install Sensu packages for Linux and Windows, Docker images for Linux containers, and binary-only distributions for Linux, Windows, macOS, FreeBSD, and Solaris." +weight: 20 +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: deploy-sensu +--- + +This installation guide describes how to install the Sensu backend, Sensu agent, and sensuctl command line tool. + +These instructions explain how to install Sensu for proof-of-concept purposes or testing in a development environment. +We recommend using a [supported package][14] to follow this guide. + +To build Sensu Go from source (OSS), follow the [Sensu Go installation instructions on GitHub][44]. + +{{% notice note %}} +**NOTE**: If you’re trying Sensu for the first time, consider following the the [Sensu Go workshop](https://github.com/sensu/sensu-go-workshop#overview) instead. +The workshop includes a local sandbox environment and a collection of resources designed to help new users learn and test Sensu.

    +If you will deploy Sensu to your infrastructure, we recommend securing your installation with transport layer security (TLS) in addition to using one of our supported packages, Docker images, or [configuration management integrations](../configuration-management/). +Read [Generate certificates](../generate-certificates) next to get the certificates you will need for TLS. +{{% /notice %}} + +Sensu downloads are provided under the [Sensu commercial license][13]. + +Sensu Go is packaged for Linux, Windows (agent and sensuctl only), macOS (sensuctl only), and Docker. +Review [supported platforms][5] for more information. + +## Architecture overview + +Sensu works differently from other monitoring and observability solutions. +Instead of provisioning each device, server, container, or sidecar you want to monitor, you install the Sensu agent on each infrastructure component. + +**Sensu agents** are lightweight clients that run on the infrastructure components you want to monitor. +Agents are responsible for creating status and metric events to send to the Sensu backend event pipeline. +Agents automatically register with Sensu as entities when you start them up and connect to the Sensu backend with no need for further provisioning. +You only need to specify the IP address for the Sensu backend server — you do not need to list the components to monitor in the backend. + +The **Sensu backend** is powered by an an embedded transport and [etcd][16] datastore. +The backend sends specific checks for each agent to execute according to the [subscriptions][41] you define in the agent configuration. +Sensu automatically downloads the files needed to run the checks from an asset repository like [Bonsai][42] or a local repo and schedules the checks on each agent. +The agents execute the checks the backend sends to their subscriptions and send the resulting status and metric events to the backend event pipeline, which gives you flexible, automated workflows to route these events. + +{{< figure src="/images/go/install_sensu/basic_architecture.png" alt="Basic Sensu architecture diagram showing agents and the backend" link="/images/go/install_sensu/basic_architecture.png" target="_blank" >}} + + +The Sensu backend keeps track of all self-registered agents. +If the backend loses a keepalive signal from any of the agents, it flags the agent and generates an event. +You can configure your instance so that when an agent (for example, a server) shuts down gracefully, the agent automatically de-registers from the backend and does not generate an alert. + +Sensu backends require persistent storage for their embedded database, disk space for local asset caching, and several exposed ports. +Agents that use Sensu [dynamic runtime assets][17] require some disk space for a local cache. + +For more information, read [Secure Sensu][8]. +Read [deployment architecture][31] and [hardware requirements][25] for deployment recommendations. + +## Ports + +Sensu backends require the following ports: + +Port | Protocol | Description | +---- | -------- | ----------- | +2379 | gRPC | Sensu storage client: Required for Sensu backends using an external etcd instance | +2380 | gRPC | Sensu storage peer: Required for etcd [cluster][22] members to communicate directly with their peers | +3000 | HTTP/HTTPS | [Sensu web UI][3]: Required for all Sensu backends using a Sensu web UI | +6060 | HTTP/HTTPS | Required for all Sensu backends when performance profiling is enabled via [debug][43] setting | +8080 | HTTP/HTTPS | [Sensu API][26]: Required for all users accessing the Sensu API | +8081 | WS/WSS | Agent API (backend WebSocket): Required for all Sensu agents connecting to a Sensu backend | + +The Sensu agent uses the following ports: + +Port | Protocol | Description | +---- | -------- | ----------- | +3030 | TCP/UDP | Sensu agent socket: Required for Sensu agents using the agent socket | +3031 | HTTP | Sensu [agent API][27]: Required for all users accessing the agent API | +8125 | UDP | [StatsD listener][28]: Required for all Sensu agents using the StatsD listener | + +The agent TCP and UDP sockets are deprecated in favor of the [agent API][27]. + +## Install the Sensu backend + +The Sensu backend is available for Debian- and RHEL-family distributions and Docker. +Review [supported platforms][5] for more information. + +### 1. Download + +{{< language-toggle >}} + +{{< code Docker >}} +# All Sensu Docker images contain a Sensu backend and a Sensu agent + +# Pull the Alpine-based image +docker pull sensu/sensu + +# Pull the image based on Red Hat Enterprise Linux +docker pull sensu/sensu-rhel +{{< /code >}} + +{{< code shell "Debian family" >}} +# Add the Sensu repository +curl -s https://packagecloud.io/install/repositories/sensu/stable/script.deb.sh | sudo bash + +# Install the sensu-go-backend package +sudo apt-get install sensu-go-backend +{{< /code >}} + +{{< code shell "RHEL family" >}} +# Add the Sensu repository +curl -s https://packagecloud.io/install/repositories/sensu/stable/script.rpm.sh | sudo bash + +# Install the sensu-go-backend package +sudo yum install sensu-go-backend +{{< /code >}} + +{{< /language-toggle >}} + +### 2. Configure and start + +You can configure the Sensu backend with `sensu-backend start` flags (recommended) or an `/etc/sensu/backend.yml` file. +The Sensu backend requires the `state-dir` flag at minimum, but other useful configurations and templates are available. + +{{% notice note %}} +**NOTE**: If you are using Docker, intitialization is included in this step when you start the backend rather than in [3. Initialize](#3-initialize). +For details about intialization in Docker, read the [backend reference](../../../observability-pipeline/observe-schedule/backend#docker-initialization). +{{% /notice %}} + +{{< language-toggle >}} + +{{< code Docker >}} +# Replace `` and `` with the username and password +# you want to use for your admin user credentials. +docker run -v /var/lib/sensu:/var/lib/sensu \ +-d --name sensu-backend \ +-p 3000:3000 -p 8080:8080 -p 8081:8081 \ +-e SENSU_BACKEND_CLUSTER_ADMIN_USERNAME= \ +-e SENSU_BACKEND_CLUSTER_ADMIN_PASSWORD= \ +sensu/sensu:latest \ +sensu-backend start --state-dir /var/lib/sensu/sensu-backend --log-level debug +{{< /code >}} + +{{< code docker "Docker Compose" >}} +# Replace `` and `` with the username and password +# you want to use for your admin user credentials. +--- +version: "3" +services: + sensu-backend: + ports: + - 3000:3000 + - 8080:8080 + - 8081:8081 + volumes: + - "sensu-backend-data:/var/lib/sensu/sensu-backend/etcd" + command: "sensu-backend start --state-dir /var/lib/sensu/sensu-backend --log-level debug" + environment: + - SENSU_BACKEND_CLUSTER_ADMIN_USERNAME= + - SENSU_BACKEND_CLUSTER_ADMIN_PASSWORD= + image: sensu/sensu:latest + +volumes: + sensu-backend-data: + driver: local + +{{< /code >}} + +{{< code shell "Debian family" >}} +# Copy the config template from the docs +sudo curl -L https://docs.sensu.io/sensu-go/latest/files/backend.yml -o /etc/sensu/backend.yml + +# Start sensu-backend using a service manager +sudo systemctl start sensu-backend + +# Verify that the backend is running +sudo systemctl status sensu-backend +{{< /code >}} + +{{< code shell "RHEL family" >}} +# Copy the config template from the docs +sudo curl -L https://docs.sensu.io/sensu-go/latest/files/backend.yml -o /etc/sensu/backend.yml + +# Start sensu-backend using a service manager +sudo systemctl start sensu-backend + +# Verify that the backend is running +sudo systemctl status sensu-backend +{{< /code >}} + +{{< /language-toggle >}} + +The backend reference includes a complete list of [configuration options][6] and [backend initialization details][30]. + +{{% notice warning %}} +**WARNING**: If you plan to [run a Sensu cluster](../cluster-sensu/), make sure that each of your backend nodes is configured, running, and a member of the cluster before you continue the installation process. +{{% /notice %}} + +### 3. Initialize + +{{% notice note %}} +**NOTE**: If you are using Docker, you already completed intitialization in [2. Configure and start](#2-configure-and-start). +Skip ahead to [4. Open the web UI](#4-open-the-web-ui) to continue the backend installation process. +If you did not use environment variables to override the default admin credentials in step 2, skip ahead to [Install sensuctl](#install-sensuctl) so you can change your default admin password immediately. +{{% /notice %}} + +**With the backend running**, run `sensu-backend init` to set up your Sensu administrator username and password. +In this initialization step, you only need to set environment variables with a username and password string — no need for role-based access control (RBAC). + +Replace `` and `` with the username and password you want to use: + +{{< language-toggle >}} + +{{< code shell "Debian family" >}} +export SENSU_BACKEND_CLUSTER_ADMIN_USERNAME= +export SENSU_BACKEND_CLUSTER_ADMIN_PASSWORD= +sensu-backend init +{{< /code >}} + +{{< code shell "RHEL family" >}} +export SENSU_BACKEND_CLUSTER_ADMIN_USERNAME= +export SENSU_BACKEND_CLUSTER_ADMIN_PASSWORD= +sensu-backend init +{{< /code >}} + +{{< /language-toggle >}} + +For details about initializing the Sensu backend, read the [backend reference][30]. + +{{% notice note %}} +**NOTE**: You may need to allow access to the [ports Sensu requires](#ports) in your local server firewall. +Refer to the documentation for your operating system to configure port access as needed. +{{% /notice %}} + +### 4. Open the web UI + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access the Sensu web UI in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} + +The web UI provides a unified view of your observability events and user-friendly tools to reduce alert fatigue. +After starting the Sensu backend, open the web UI by visiting http://localhost:3000. +You may need to replace `localhost` with the hostname or IP address where the Sensu backend is running. + +To log in to the web UI, enter your Sensu user credentials. +If you are using Docker and you did not specify environment variables to override the default admin credentials, your user credentials are username `admin` and password `P@ssw0rd!`. +Otherwise, your user credentials are the username and password you provided with the `SENSU_BACKEND_CLUSTER_ADMIN_USERNAME` and `SENSU_BACKEND_CLUSTER_ADMIN_PASSWORD` environment variables. + +Select the ☰ icon to explore the web UI. + +### 5. Make a request to the /health API + +To make sure the backend is up and running, use the Sensu [/health API][35] to check the backend's health. +You should receive a response that includes `"Healthy": true`. + +{{< code shell >}} +curl http://127.0.0.1:8080/health +{{< /code >}} + +Now that you've installed the Sensu backend, [install and configure sensuctl][19] to connect to your backend URL. +Then you can [install a Sensu agent][18] and start monitoring your infrastructure. + +## Install sensuctl + +[Sensuctl][4] is a command line tool for managing resources within Sensu. +It works by calling Sensu’s HTTP API to create, read, update, and delete resources, events, and entities. +Sensuctl is available for Linux, Windows, and macOS. + +To install sensuctl: + +{{< language-toggle >}} + +{{< code shell "Debian family" >}} +# Add the Sensu repository +curl -s https://packagecloud.io/install/repositories/sensu/stable/script.deb.sh | sudo bash + +# Install the sensu-go-cli package +sudo apt-get install sensu-go-cli +{{< /code >}} + +{{< code shell "RHEL family" >}} +# Add the Sensu repository +curl https://packagecloud.io/install/repositories/sensu/stable/script.rpm.sh | sudo bash + +# Install the sensu-go-cli package +sudo yum install sensu-go-cli +{{< /code >}} + +{{< code powershell "Windows" >}} +# Download sensuctl for Windows amd64 +Invoke-WebRequest https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_windows_amd64.zip -OutFile C:\Users\Administrator\sensu-go_6.12.0_windows_amd64.zip + +# Or for Windows 386 +Invoke-WebRequest https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0//sensu-go_6.12.0_windows_386.zip -OutFile C:\Users\Administrator\sensu-go_6.12.0_windows_386.zip + +# Unzip the file with PowerShell for Windows amd64 +Expand-Archive -LiteralPath 'C:\Users\Administrator\sensu-go_6.12.0_windows_amd64.zip' -DestinationPath 'C:\\Program Files\sensu\sensuctl\bin' + +# or for Windows 386 +Expand-Archive -LiteralPath 'C:\Users\Administrator\sensu-go_6.12.0_windows_386.zip' -DestinationPath 'C:\\Program Files\sensu\sensuctl\bin' +{{< /code >}} + +{{< code shell "macOS" >}} +# Download the latest release +curl -LO https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_darwin_amd64.tar.gz + +# Extract the archive +tar -xvf sensu-go_6.12.0_darwin_amd64.tar.gz + +# Copy the executable into your PATH +sudo cp sensuctl /usr/local/bin/ +{{< /code >}} + +{{< /language-toggle >}} + +To start using sensuctl, run `sensuctl configure` and log in with your user credentials, namespace, and [Sensu backend][21] URL. +To configure sensuctl using default values: + +{{< code text >}} +sensuctl configure -n \ +--username 'YOUR_USERNAME' \ +--password 'YOUR_PASSWORD' \ +--namespace default \ +--url 'http://127.0.0.1:8080' +{{< /code >}} + +Here, the `-n` flag triggers non-interactive mode. +Run `sensuctl config view` to view your user profile. + +For more information about sensuctl, read the [sensuctl documentation][4]. + +### Change default admin password + +If you are using Docker and you did not use environment variables to override the default admin credentials in [step 2 of the backend installation process](#2-configure-and-start), we recommend that you change the default admin password as soon as you have [installed sensuctl][19]. +Run: + +{{< code shell >}} +sensuctl user change-password --interactive +{{< /code >}} + +## Install Sensu agents + +The Sensu agent is available for Debian- and RHEL-family distributions, Windows, and Docker. +Review [supported platforms][5] for more information. + +### 1. Download {#agent-download} + +{{< language-toggle >}} + +{{< code Docker >}} +# All Sensu images contain a Sensu backend and a Sensu agent + +# Pull the Alpine-based image +docker pull sensu/sensu + +# Pull the RHEL-based image +docker pull sensu/sensu-rhel +{{< /code >}} + +{{< code shell "Debian family" >}} +# Add the Sensu repository +curl -s https://packagecloud.io/install/repositories/sensu/stable/script.deb.sh | sudo bash + +# Install the sensu-go-agent package +sudo apt-get install sensu-go-agent +{{< /code >}} + +{{< code shell "RHEL family" >}} +# Add the Sensu repository +curl -s https://packagecloud.io/install/repositories/sensu/stable/script.rpm.sh | sudo bash + +# Install the sensu-go-agent package +sudo yum install sensu-go-agent +{{< /code >}} + +{{< code powershell "Windows" >}} +# Download the Sensu agent for Windows amd64 +Invoke-WebRequest https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go-agent_6.12.0.7321_en-US.x64.msi -OutFile "$env:userprofile\sensu-go-agent_6.12.0.7321_en-US.x64.msi" + +# Or for Windows 386 +Invoke-WebRequest https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go-agent_6.12.0.7321_en-US.x86.msi -OutFile "$env:userprofile\sensu-go-agent_6.12.0.7321_en-US.x86.msi" + +# Install the Sensu agent for Windows amd64 +msiexec.exe /i $env:userprofile\sensu-go-agent_6.12.0.7321_en-US.x64.msi /qn + +# Or for Windows 386 +msiexec.exe /i $env:userprofile\sensu-go-agent_6.12.0.7321_en-US.x86.msi /qn + +# Or via Chocolatey +choco install sensu-agent + +{{< /code >}} +{{< /language-toggle >}} + +### 2. Configure and start {#agent-start} + +You can configure the Sensu agent with `sensu-agent start` flags (recommended) or an `/etc/sensu/agent.yml` file. +The Sensu agent requires the `--backend-url` flag at minimum, but other useful configurations and templates are available. + +{{< language-toggle >}} + +{{< code Docker >}} +# If you are running the agent locally on the same system as the Sensu backend, +# add `--link sensu-backend` to your Docker arguments and change the backend +# URL to `--backend-url ws://sensu-backend:8081`. + +# Start an agent with the system subscription +docker run -v /var/lib/sensu:/var/lib/sensu -d \ +--name sensu-agent sensu/sensu:latest \ +sensu-agent start --backend-url ws://sensu.yourdomain.com:8081 --log-level debug --subscriptions system --api-host 0.0.0.0 --cache-dir /var/lib/sensu +{{< /code >}} + +{{< code docker "Docker Compose" >}} +# Start an agent with the system subscription +--- +version: "3" +services: + sensu-agent: + image: sensu/sensu:latest + ports: + - 3031:3031 + volumes: + - "sensu-agent-data:/var/lib/sensu" + command: "sensu-agent start --backend-url ws://sensu-backend:8081 --log-level debug --subscriptions system --api-host 0.0.0.0 --cache-dir /var/lib/sensu" + +volumes: + sensu-agent-data: + driver: local +{{< /code >}} + +{{< code shell "Debian family" >}} +# Copy the config template from the docs +sudo curl -L https://docs.sensu.io/sensu-go/latest/files/agent.yml -o /etc/sensu/agent.yml + +# Start sensu-agent using a service manager +sudo systemctl start sensu-agent +{{< /code >}} + +{{< code shell "RHEL family" >}} +# Copy the config template from the docs +sudo curl -L https://docs.sensu.io/sensu-go/latest/files/agent.yml -o /etc/sensu/agent.yml + +# Start sensu-agent using a service manager +sudo systemctl start sensu-agent +{{< /code >}} + +{{< code powershell "Windows" >}} +# Copy the example agent config file from %ALLUSERSPROFILE%\sensu\config\agent.yml.example +# (default: C:\ProgramData\sensu\config\agent.yml.example) to C:\ProgramData\sensu\config\agent.yml +cp C:\ProgramData\sensu\config\agent.yml.example C:\ProgramData\sensu\config\agent.yml + +# Change to the sensu\sensu-agent\bin directory where you installed Sensu +cd 'C:\Program Files\sensu\sensu-agent\bin' + +# Run the sensu-agent executable +./sensu-agent.exe + +# Install and start the agent +./sensu-agent service install + +{{< /code >}} + +{{< /language-toggle >}} + +The agent reference includes a complete list of [configuration options][7]. + +### 3. Verify keepalive events + +Sensu keepalives are the heartbeat mechanism used to ensure that all registered agents are operating and can reach the Sensu backend. +To confirm that the agent is registered with Sensu and is sending keepalive events, open the entity page in the [Sensu web UI][24] or run `sensuctl entity list`. + +### 4. Verify an example event + +With your backend and agent still running, send this request to the Sensu core/v2/events API: + +{{< code shell >}} +curl -X POST \ +-H 'Content-Type: application/json' \ +-d '{ + "check": { + "metadata": { + "name": "check-mysql-status" + }, + "status": 1, + "output": "could not connect to mysql" + } +}' \ +http://127.0.0.1:3031/events +{{< /code >}} + +This request creates a `warning` event that you can [view in your web UI Events page][32]. + +To create an OK event, change the `status` to `0` and resend. +You can change the `output` value to `connected to mysql` to use a different message for the OK event. + +## Next steps + +Now that you have installed Sensu, you’re ready to build your observability pipelines! +Here are some ideas for next steps. + +### Get started with Sensu + +If you're ready to try Sensu, one of these pathways can get you started: + +- Manually trigger an event that [sends alerts to your email inbox][12]. +- [Create a check to monitor CPU usage][9] and [send Slack alerts based on your check][10]. +- [Collect metrics][33] with a Sensu check and use a handler to [populate metrics in InfluxDB][37]. +- Use the [sensuctl dump][38] command to export all of your events and resources as a backup — then use [sensuctl create][39] to restore if needed. + +### Deploy Sensu outside your local development environment + +To deploy Sensu for use outside of a local development environment, first decide whether you want to [run a Sensu cluster][22]. +A Sensu cluster is a group of three or more sensu-backend nodes, each connected to a shared database provided either by Sensu’s embedded etcd or an external etcd cluster. + +Clustering allows you to absorb the loss of a backend node, prevent data loss, and distribute the network load of agents. +However, scaling a single backend to a cluster or migrating a cluster from cleartext HTTP to encrypted HTTPS without downtime can require [a number of tedious steps][40]. +For this reason, we recommend that you decide whether your deployment will require clustering as part of your initial planning effort. + +No matter whether you deploy a single backend or a clustered configuration, begin by securing Sensu with transport layer security (TLS). +The first step in setting up TLS is to [generate the certificates you need][2]. +Then, follow our [Secure Sensu][8] guide to make Sensu production-ready. + +After you've secured Sensu, read [Run a Sensu cluster][22] if you are setting up a clustered configuration. + +## Commercial features + +Sensu Inc. offers support packages for Sensu Go and [commercial features][20] designed for monitoring at scale. + +All commercial features are [free for your first 100 entities][29]. +To learn more about Sensu Go commercial licenses for more than 100 entities, [contact the Sensu sales team][11]. + +If you already have a Sensu commercial license, [log in to your Sensu account][34] and download your license file. +Save your license to a file such as `sensu_license.yml` or `sensu_license.json`. + +Use sensuctl to activate your license: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl create --file sensu_license.yml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl create --file sensu_license.json +{{< /code >}} + +{{< /language-toggle >}} + +You can use sensuctl to view your license details at any time. + +{{< code shell >}} +sensuctl license info +{{< /code >}} + + +[1]: https://github.com/sensu/sensu-go/releases/ +[2]: ../generate-certificates/ +[3]: ../../../web-ui/ +[4]: ../../../sensuctl/ +[5]: ../../../platforms/ +[6]: ../../../observability-pipeline/observe-schedule/backend/#backend-configuration-options +[7]: ../../../observability-pipeline/observe-schedule/agent/#agent-configuration-options +[8]: ../secure-sensu/ +[9]: ../../../observability-pipeline/observe-schedule/monitor-server-resources/ +[10]: ../../../observability-pipeline/observe-process/send-slack-alerts/ +[11]: https://sensu.io/contact?subject=contact-sales/ +[12]: ../../../observability-pipeline/observe-process/send-email-alerts/ +[13]: https://sensu.io/licenses +[14]: ../../../platforms/#supported-packages +[15]: ../../../observability-pipeline/observe-schedule/agent/#example-post-request-to-events-endpoint +[16]: https://etcd.io/ +[17]: ../../../plugins/assets/ +[18]: #install-sensu-agents +[19]: #install-sensuctl +[20]: ../../../commercial/ +[21]: #install-the-sensu-backend +[22]: ../cluster-sensu/ +[24]: #4-open-the-web-ui +[25]: ../hardware-requirements/ +[26]: ../../../api/ +[27]: ../../../observability-pipeline/observe-schedule/agent#create-observability-events-using-the-agent-api +[28]: ../../../observability-pipeline/observe-schedule/agent#create-observability-events-using-the-statsd-listener +[29]: https://sensu.io/blog/one-year-of-sensu-go/ +[30]: ../../../observability-pipeline/observe-schedule/backend#initialization +[31]: ../deployment-architecture/ +[32]: http://localhost:3000/ +[33]: ../../../observability-pipeline/observe-schedule/collect-metrics-with-checks/ +[34]: https://account.sensu.io/ +[35]: ../../../api/other/health/ +[36]: #4-open-the-web-ui +[37]: ../../../observability-pipeline/observe-process/populate-metrics-influxdb/ +[38]: ../../../sensuctl/back-up-recover/ +[39]: ../../../sensuctl/create-manage-resources/#create-resources +[40]: https://etcd.io/docs/latest/op-guide/runtime-configuration/ +[41]: ../../../observability-pipeline/observe-schedule/subscriptions +[42]: https://bonsai.sensu.io/ +[43]: ../../../observability-pipeline/observe-schedule/backend/#debug-attribute +[44]: https://github.com/sensu/sensu-go#installation diff --git a/content/sensu-go/6.12/operations/deploy-sensu/scale-event-storage.md b/content/sensu-go/6.12/operations/deploy-sensu/scale-event-storage.md new file mode 100644 index 0000000000..175d4effe2 --- /dev/null +++ b/content/sensu-go/6.12/operations/deploy-sensu/scale-event-storage.md @@ -0,0 +1,489 @@ +--- +title: "Scale Sensu Go with Enterprise datastore" +linkTitle: "Scale with Enterprise Datastore" +guide_title: "Scale Sensu Go with Enterprise datastore" +type: "guide" +description: "Use Sensu's Enterprise datastore to scale your monitoring to thousands of events per second and minimize the replication communication between etcd peers." +weight: 120 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: deploy-sensu +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access the datastore feature in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} + +Sensu Go's datastore feature enables scaling your monitoring to many thousands of events per second. + +For each unique entity/check pair, Sensu records the latest event object in its datastore. +By default, Sensu uses the embedded etcd datastore for event storage. +The embedded etcd datastore helps you get started, but as the number of entities and checks in your Sensu implementation grows, so does the rate of events being written to the datastore. +In a clustered deployment of etcd, whether embedded or external to Sensu, each event received by a member of the cluster must be replicated to other members, increasing network and disk IO utilization. + +Our team documented configuration and testing of Sensu running on bare metal infrastructure in the [sensu/sensu-perf][1] project. +This configuration comfortably handled 12,000 Sensu agent connections (and their keepalives) and processed more than 8,500 events per second. + +This rate of events should be sufficient for many installations but assumes an ideal scenario where Sensu backend nodes use direct-attached, dedicated non-volatile memory express (NVMe) storage and are connected to a dedicated LAN. +Deployments on public cloud providers are not likely to achieve similar results due to sharing both disk and network bandwidth with other tenants. +Adhering to the cloud provider's recommended practices may also become a factor because many operators are inclined to deploy a cluster across multiple availability zones. +In such a deployment cluster, communication happens over shared WAN links, which are subject to uncontrolled variability in throughput and latency. + +The Enterprise datastore can help operators achieve much higher rates of event processing and minimize the replication communication between etcd peers. +The `sensu-perf` test environment comfortably handles 40,000 Sensu agent connections (and their keepalives) and processes more than 36,000 events per second under ideal conditions. + +{{% notice warning %}} +**IMPORTANT**: PostgreSQL configuration file locations differ depending on platform. +The steps in this guide use common paths for RHEL-family distributions, but the files may be stored elsewhere on your system. +Learn more about [PostgreSQL configuration file locations](https://www.postgresql.org/docs/current/runtime-config-file-locations.html). +{{% /notice %}} + +## Prerequisites + +* Database server running Postgres 9.5 or later +* Postgres database (or administrative access to create one) +* Postgres user with permissions to the database (or administrative access to create such a user) +* [Licensed Sensu Go backend][3] + +For optimal performance, we recommend the following PostgreSQL configuration parameters and settings as a starting point for your `postgresql.conf` file: + +{{< code postgresql >}} +max_connections = 200 + +shared_buffers = 10GB + +maintenance_work_mem = 1GB + +vacuum_cost_delay = 10ms +vacuum_cost_limit = 10000 + +bgwriter_delay = 50ms +bgwriter_lru_maxpages = 1000 + +max_worker_processes = 8 +max_parallel_maintenance_workers = 2 +max_parallel_workers_per_gather = 2 +max_parallel_workers = 8 + +synchronous_commit = off + +wal_sync_method = fdatasync +wal_writer_delay = 5000ms +max_wal_size = 5GB +min_wal_size = 1GB + +checkpoint_completion_target = 0.9 + +autovacuum_naptime = 10s +autovacuum_vacuum_scale_factor = 0.05 +autovacuum_analyze_scale_factor = 0.025 +{{< /code >}} + +Adjust the parameters and settings as needed based on your hardware and the performance you observe. +Read the [PostgreSQL parameters documentation][2] for information about setting parameters. + +## Configure Postgres + +Before Sensu can start writing events to Postgres, you need a database and an account with permissions to write to that database. +To provide consistent event throughput, we recommend exclusively dedicating your Postgres instance to storage of Sensu events. + +If you have administrative access to Postgres, you can create the database and user. + +1. Change to the postgres user and open the Postgres prompt (`postgres=#`): + + {{< code shell >}} +sudo -u postgres psql +{{< /code >}} + +2. Create the `sensu_events` database: + + {{< code postgresql >}} +CREATE DATABASE sensu_events; +{{< /code >}} + + PostgreSQL will return a confirmation message: `CREATE DATABASE`. + +3. Create the `sensu` role with a password: + + {{< code postgresql >}} +CREATE USER sensu WITH ENCRYPTED PASSWORD 'mypass'; +{{< /code >}} + + PostgreSQL will return a confirmation message: `CREATE ROLE`. + +4. Grant the `sensu` role all privileges for the `sensu_events` database: + + {{< code postgresql >}} +GRANT ALL PRIVILEGES ON DATABASE sensu_events TO sensu; +{{< /code >}} + + PostgreSQL will return a confirmation message: `GRANT`. + +5. Grant the `sensu` role all privileges to the `public` schema (`This step is mandatory for Postgres 15`): + + {{< code postgresql >}} +GRANT ALL ON SCHEMA public TO sensu; +{{< /code >}} + + PostgreSQL will return a confirmation message: `GRANT`. + +6. Type `\q` to exit the PostgreSQL prompt. + +With this configuration complete, PostgreSQL will have a `sensu_events` database for storing Sensu events and a `sensu` user with permissions to that database. + +By default, the Postgres user you've just added will not be able to authenticate via password, so you'll also need to make a change to the `pg_hba.conf` file. +The required change will depend on how Sensu will connect to Postgres. +In this case, you'll configure Postgres to allow the `sensu` user to connect to the `sensu_events` database from any host using an [md5][5]-encrypted password: + +1. Make a copy of the current `pg_hba.conf` file: + + {{< code shell >}} +sudo cp /var/lib/pgsql/data/pg_hba.conf /var/tmp/pg_hba.conf.bak +{{< /code >}} + +2. Give the Sensu user permissions to connect to the `sensu_events` database from any IP address: + + {{< code shell >}} +echo 'host sensu_events sensu 0.0.0.0/0 md5' | sudo tee -a /var/lib/pgsql/data/pg_hba.conf +{{< /code >}} + +3. Restart the postgresql service to activate the `pg_hba.conf` changes: + + {{< code shell >}} +sudo systemctl restart postgresql +{{< /code >}} + +With this configuration complete, you can configure Sensu to store events in your Postgres database. + +To secure communication between Sensu and the PostgreSQL event store using certificate authentication, read [Secure PostgreSQL][7]. + +## Configure Sensu + +If your Sensu backend is already licensed, the configuration for routing events to Postgres is relatively straightforward. +Create a `PostgresConfig` resource that describes the database connection as a data source name (DSN): + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: PostgresConfig +api_version: store/v1 +metadata: + name: postgres01 +spec: + dsn: "postgresql://sensu:mypass@10.0.2.15:5432/sensu_events?sslmode=disable" + pool_size: 20 +{{< /code >}} + +{{< code json >}} +{ + "type": "PostgresConfig", + "api_version": "store/v1", + "metadata": { + "name": "my-postgres" + }, + "spec": { + "dsn": "postgresql://sensu:mypass@10.0.2.15:5432/sensu_events", + "pool_size": 20 + } +} +{{< /code >}} + +{{< /language-toggle >}} + +Save this configuration as `my-postgres.yml` or `my-postgres.json` and install it with `sensuctl`: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl create --file my-postgres.yml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl create --file my-postgres.json +{{< /code >}} + +{{< /language-toggle >}} + +The Sensu backend is now configured to use Postgres for event storage! + +In the web UI and in sensuctl, event history will appear incomplete. +When Postgres configuration is provided and the backend successfully connects to the database, etcd event history is not migrated. +New events will be written to Postgres as they are processed, with the Postgres datastore ultimately being brought up to date with the current state of your monitored infrastructure. + +Aside from event history, which is not migrated from etcd, there's no observable difference when using Postgres as the event store, and neither interface supports displaying the PostgresConfig type. + +To verify that the change was effective and your connection to Postgres was successful, look at the [sensu-backend log][4]: + +{{< code text >}} +{"component":"store","level":"warning","msg":"trying to enable external event store","time":"2019-10-02T23:31:38Z"} +{"component":"store","level":"warning","msg":"switched event store to postgres","time":"2019-10-02T23:31:38Z"} +{{< /code >}} + +You can also use `psql` to verify that events are being written to the `sensu_events` database. + +1. Change to the postgres user and open the Postgres prompt (`postgres=#`): + + {{< code shell >}} +sudo -u postgres psql +{{< /code >}} + +2. Connect to the `sensu_events` database: + + {{< code postgresql >}} +\c sensu_events +{{< /code >}} + + PostgreSQL will return a confirmation message: + + {{< code text >}} +You are now connected to database "sensu_events" as user "postgres". +{{< /code >}} + + The prompt will change to `sensu_events=#`. + +3. List the tables in the `sensu_events` database: + + {{< code postgresql >}} +\dt +{{< /code >}} + + PostgreSQL will list the tables: + + {{< code text >}} + List of relations + Schema | Name | Type | Owner +--------+-------------------+-------+------- + public | events | table | sensu + public | migration_version | table | sensu +(2 rows) +{{< /code >}} + +4. Request a list of all entities reporting keepalives: + + {{< code postgresql >}} +select sensu_entity from events where sensu_check = 'keepalive'; +{{< /code >}} + + PostgreSQL will return a list of the entities: + + {{< code text >}} + sensu_entity +-------------- + i-414141 + i-424242 + i-434343 +(3 rows) +{{< /code >}} + +## Revert to the built-in datastore + +If you want to revert to the default etcd event store, delete the PostgresConfig resource. +In this example, `my-postgres.yml` or `my-postgres.json` contain the same configuration you used to configure the Enterprise event store earlier in this guide: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl delete --file my-postgres.yml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl delete --file my-postgres.json +{{< /code >}} + +{{< /language-toggle >}} + +To verify that the change was effective, look for messages similar to these in the [sensu-backend log][4]: + +{{< code text >}} +{"component":"store","level":"warning","msg":"store configuration deleted","store":"/sensu.io/api/enterprise/store/v1/provider/postgres01","time":"2019-10-02T23:29:06Z"} +{"component":"store","level":"warning","msg":"switched event store to etcd","time":"2019-10-02T23:29:06Z"} +{{< /code >}} + +Similar to enabling PostgreSQL, switching back to the etcd datastore does not migrate current observability event data from one store to another. +The web UI or sensuctl output may list outdated events until the etcd datastore catches up with the current state of your monitored infrastructure. + +## Configure Postgres streaming replication + +Postgres supports an active standby with [streaming replication][6]. +Configure streaming replication to replicate all Sensu events written to the primary Postgres server to the standby server. + +Follow the steps in this section to create and add the replication role, set streaming replication configuration parameters, bootstrap the standby host, and confirm successful Postgres streaming replication. + +### Create and add the replication role + +If you have administrative access to Postgres, you can create the replication role. +Follow these steps to create and add the replication role on the **primary** Postgres host: + +1. Change to the postgres user and open the Postgres prompt (`postgres=#`): +{{< code shell >}} +sudo -u postgres psql +{{< /code >}} + +2. Create the `repl` role: +{{< code postgresql >}} +CREATE ROLE repl PASSWORD '' LOGIN REPLICATION; +{{< /code >}} + + PostgreSQL will return a confirmation message: `CREATE ROLE`. + +3. Type `\q` to exit the PostgreSQL prompt. + +4. Add the replication role to `pg_hba.conf` using an [md5-encrypted password][5]. +Make a copy of the current `pg_hba.conf`: +{{< code shell >}} +sudo cp /var/lib/pgsql/data/pg_hba.conf /var/tmp/pg_hba.conf.bak +{{< /code >}} + +5. In the following command, replace `` with the IP address of your standby Postgres host and run the command: +{{< code shell >}} +export STANDBY_IP= +{{< /code >}} + +6. Give the repl user permissions to replicate from the standby host: +{{< code shell >}} +echo "host replication repl ${STANDBY_IP}/32 md5" | sudo tee -a /var/lib/pgsql/data/pg_hba.conf +{{< /code >}} + +7. Restart the PostgreSQL service to activate the `pg_hba.conf` changes: +{{< code shell >}} +sudo systemctl restart postgresql +{{< /code >}} + +### Set streaming replication configuration parameters + +Follow these steps to set streaming replication configuration parameters on the **primary** Postgres host: + +1. Make a copy of the `postgresql.conf`: +{{< code shell >}} +sudo cp -a /var/lib/pgsql/data/postgresql.conf /var/lib/pgsql/data/postgresql.conf.bak +{{< /code >}} + +2. Append the necessary configuration options. +{{< code shell >}} +echo 'wal_level = replica' | sudo tee -a /var/lib/pgsql/data/postgresql.conf +{{< /code >}} + +3. Set the maximum number of concurrent connections from the standby servers: +{{< code shell >}} +echo 'max_wal_senders = 5' | sudo tee -a /var/lib/pgsql/data/postgresql.conf +{{< /code >}} + +4. To prevent the primary server from removing the WAL segments required for the standby server before shipping them, set the minimum number of segments retained in the `pg_xlog` directory: +{{< code shell >}} +echo 'wal_keep_segments = 32' | sudo tee -a /var/lib/pgsql/data/postgresql.conf +{{< /code >}} + + At minimum, the number of `wal_keep_segments` should be larger than the number of segments generated between the beginning of online backup and the startup of streaming replication. + + {{% notice note %}} +**NOTE**: If you enable WAL archiving to an archive directory accessible from the standby, this step may not be necessary. +{{% /notice %}} + +5. Restart the PostgreSQL service to activate the `postgresql.conf` changes: +{{< code shell >}} +sudo systemctl restart postgresql +{{< /code >}} + +### Bootstrap the standby host + +Follow these steps to bootstrap the standby host on the **standby** Postgres host: + +1. If the standby host has ever run Postgres, stop Postgres and empty the data directory: +{{< code shell >}} +sudo systemctl stop postgresql +{{< /code >}} + + {{< code shell >}} +sudo mv /var/lib/pgsql/data /var/lib/pgsql/data.bak +{{< /code >}} + +2. Make the standby data directory: +{{< code shell >}} +sudo install -d -o postgres -g postgres -m 0700 /var/lib/pgsql/data +{{< /code >}} + +3. In the following command, replace `` with the IP address of your primary Postgres host and run the command: +{{< code shell >}} +export PRIMARY_IP= +{{< /code >}} + +4. Bootstrap the standby data directory: +{{< code shell >}} +sudo -u postgres pg_basebackup -h $PRIMARY_IP -D /var/lib/pgsql/data -P -U repl -R --wal-method=stream +{{< /code >}} + +5. Enter your password at the Postgres prompt: +{{< code postgresql >}} +Password: +{{< /code >}} + +After you enter your password, PostgreSQL will list database copy progress: + +{{< code text >}} +30318/30318 kB (100%), 1/1 tablespace +{{< /code >}} + +### Confirm replication + +Follow these steps to confirm replication: + +1. On the **primary** Postgres host, remove primary-only configurations: +{{< code shell >}} +sudo sed -r -i.bak '/^(wal_level|max_wal_senders|wal_keep_segments).*/d' /var/lib/pgsql/data/postgresql.conf +{{< /code >}} + +2. Start the PostgreSQL service: +{{< code shell >}} +sudo systemctl start postgresql +{{< /code >}} + +3. Check the primary host commit log location: +{{< code shell >}} +sudo -u postgres psql -c "select pg_current_wal_lsn()" +{{< /code >}} + + PostgreSQL will list the primary host commit log location: +{{< code text >}} + pg_current_wal_lsn +-------------------------- + 0/3000568 +(1 row) +{{< /code >}} + +4. On the **standby** Postgres host, check the commit log location: +{{< code shell >}} +sudo -u postgres psql -c "select pg_last_wal_receive_lsn()" +{{< /code >}} +{{< code shell >}} +sudo -u postgres psql -c "select pg_last_wal_replay_lsn()" +{{< /code >}} + + PostgreSQL will list the standby host commit log location: +{{< code text >}} + pg_last_wal_receive_lsn +------------------------------- + 0/3000568 +(1 row) +{{< /code >}} +{{< code text >}} + pg_last_wal_replay_lsn +------------------------------ + 0/3000568 +(1 row) +{{< /code >}} + +With this configuration complete, your Sensu events will be replicated to the standby host. + + +[1]: https://github.com/sensu/sensu-perf +[2]: https://www.postgresql.org/docs/current/config-setting.html +[3]: ../../../commercial/ +[4]: ../../maintain-sensu/troubleshoot/#log-file-locations +[5]: https://www.postgresql.org/docs/9.5/auth-methods.html#AUTH-PASSWORD +[6]: https://wiki.postgresql.org/wiki/Streaming_Replication +[7]: ../secure-postgres/ diff --git a/content/sensu-go/6.12/operations/deploy-sensu/secure-postgres.md b/content/sensu-go/6.12/operations/deploy-sensu/secure-postgres.md new file mode 100644 index 0000000000..160e76a2f6 --- /dev/null +++ b/content/sensu-go/6.12/operations/deploy-sensu/secure-postgres.md @@ -0,0 +1,496 @@ +--- +title: "Secure PostgreSQL" +linkTitle: "Secure PostgreSQL" +guide_title: "Secure PostgreSQL" +type: "guide" +description: "Learn how to secure communication between Sensu and the enterprise PostgreSQL event store with certificate authentication." +weight: 65 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: deploy-sensu +--- + +This guide describes how to secure communication between Sensu and the PostgreSQL event store using certificate authentication. +When deploying Sensu for use outside of a local development environment, you should secure it using transport layer security (TLS). + +To learn how to secure communications between Sensu and its agents, read [Generate certificates for your Sensu installation][3] and [Secure Sensu][1]. + +{{% notice note %}} +**NOTE**: This guide describes one option for securing communication between Sensu and PostgreSQL and is intended as a starting point. +Your organization's needs may require a different approach. +{{% /notice %}} + +## Prerequisites + +To use this guide, you must have: + +- A running Sensu deployment. +- A running PostgreSQL instance that you've configured according to [Scale Sensu Go with Enterprise datastore][4]. +The commands in this guide use PostgreSQL version 14. + +## Install cfssl + +The [CloudFlare cfssl][2] toolkit is released as a collection of command-line tools. + +If you followed [Generate certificates for your Sensu installation][3], you already downloaded and installed the Cloudflare cfssl toolkit. +If not, run the following commands: + +{{< language-toggle >}} + +{{< code shell "RHEL family" >}} +sudo curl -s -L -o /bin/cfssl https://github.com/cloudflare/cfssl/releases/download/v1.6.2/cfssl_1.6.2_linux_amd64 +sudo curl -s -L -o /bin/cfssljson https://github.com/cloudflare/cfssl/releases/download/v1.6.2/cfssljson_1.6.2_linux_amd64 +sudo curl -s -L -o /bin/cfssl-certinfo https://github.com/cloudflare/cfssl/releases/download/v1.6.2/cfssl-certinfo_1.6.2_linux_amd64 +sudo chmod +x /bin/cfssl* +{{< /code >}} + +{{< code shell "Debian family" >}} + +# Update apt repos +sudo apt-get update + +# Install cfssl +sudo apt-get install golang-cfssl + +{{< /code >}} + +{{< /language-toggle >}} + +To verify that cfssl is installed, run: + +{{< code shell >}} +cfssl version +{{< /code >}} + +## Create a Certificate Authority (CA) + +Follow these steps to create a CA with cfssl and cfssljson: + +1. Create `/etc/sensu/tls` (which does not exist by default): +{{< code shell >}} +mkdir -p /etc/sensu/tls +{{< /code >}} + +2. Navigate to the new `/etc/sensu/tls` directory: +{{< code shell >}} +cd /etc/sensu/tls +{{< /code >}} + +3. Create the CA: +{{< code shell >}} +echo '{"CN":"Sensu Test CA","key":{"algo":"rsa","size":2048}}' | cfssl gencert -initca - | cfssljson -bare ca - +{{< /code >}} + +4. Define signing parameters and profiles: +{{< code shell >}} +echo '{"signing":{"default":{"expiry":"17520h","usages":["signing","key encipherment","client auth"]},"profiles":{"postgresql":{"usages":["signing","key encipherment","server auth","client auth"],"expiry":"4320h"},"backend":{"usages":["signing","key encipherment","client auth"],"expiry":"4320h"}}}}' > ca-config.json +{{< /code >}} +{{% notice note %}} +**NOTE**: We suggest a 6-month expiry duration for security, but you can use any duration you prefer when you define the `expiry` attribute value in the signing parameters. +{{% /notice %}} + + + +You should now have a directory at `/etc/sensu/tls` that contains the following files: + + filename | description | +-----------------|-------------| +`ca.pem` | CA root certificate. Required for all systems running the Sensu backend or agent. The agent and backend use `ca.pem` to validate server certificates at connection time. | +`ca-key.pem` | CA root certificate private key. | +`ca-config.json` | CA signing parameters and profiles. Not used by Sensu. | +`ca.csr` | Certificate signing request for the CA root certificate. Not used by Sensu. | + +## Generate certificate and key for PostgreSQL + +Next, generate the certificates you need for PostgreSQL. + + + +This guide assumes your PostgreSQL instance is reachable via a `10.0.0.x` IP address, a fully qualified name (for example, `postgres.example.com`), and an unqualified name (for example, `postgres`): + +Unqualified
    name | IP address | Fully qualified
    domain name
    (FQDN) | Additional
    names | +-----------------|------------|------------------------------------|----------------------| +postgres | 10.0.0.43 | postgres.example.com | localhost, 127.0.0.1 | + +The additional names for localhost and 127.0.0.1 are added here for convenience and are not strictly required. + +- The values provided for the ADDRESS variable will be used to populate the certificate's SAN records. +For systems with multiple hostnames and IP addresses, add each to the comma-delimited value of the ADDRESS variable. +- The value provided for the NAME variable will be used to populate the certificate's CN record. +It will also be used in the names for the `*.pem` and `*.csr` files. + +For example: + +{{< code shell >}} +export ADDRESS=localhost,127.0.0.1,10.0.0.43,postgres,postgres.example.com +export NAME=postgres.example.com +echo '{"CN":"'$NAME'","hosts":[""],"key":{"algo":"rsa","size":2048}}' | cfssl gencert -config=ca-config.json -profile="postgresql" -ca=ca.pem -ca-key=ca-key.pem -hostname="$ADDRESS" - | cfssljson -bare $NAME +{{< /code >}} + +The `/etc/sensu/tls` directory should now include the following files for your PostgreSQL instance: + + filename | description | +-----------------|-------------| +`postgres.example.com.pem` | The certificate that your PostgreSQL instance will use.| +`postgres.example.com-key.pem` | The private key that your PostgreSQL instance will use. | +`postgres.example.com.csr` | Certificate signing request for the PostgreSQL certificate. Not used. | + +## Generate certificate and key for your Sensu backend + +Just like the certificate and key for PostgreSQL, you'll need a certificate and key for the Sensu backend. + +To generate the backend certificate and key, run: + +{{< code shell >}} +export POSTGRES_USERNAME=sensu +echo '{"CN":"'$POSTGRES_USERNAME'","hosts":[""],"key":{"algo":"rsa","size":2048}}' | cfssl gencert -config=ca-config.json -ca=ca.pem -ca-key=ca-key.pem -hostname="" -profile=backend - | cfssljson -bare $POSTGRES_USERNAME + +{{< /code >}} + +You'll also need to change the ownership of the certificate files to the `sensu` user: + +{{< code shell >}} + +chown -R sensu:sensu /etc/sensu/tls + +{{< /code >}} + +You should now have the following files in your `/etc/sensu/tls` directory, which the Sensu backend will use to communicate with PostgreSQL: + + filename | description | +-----------------|-------------| +`sensu.pem` | The certificate that your Sensu backend will use.| +`sensu-key.pem` | The private key that your Sensu backend will use. | +`sensu.csr` | Certificate signing request for the Sensu backend certificate. Not used. | + +Now that you have the required certificates and keys, you can configure Sensu to use certificate authentication with PostgreSQL. + +{{% notice warning %}} +**WARNING**: Once you've generated all of your certificates, delete the `ca-key.pem` file from the `/etc/sensu/tls` directory. +The `ca-key.pem` file contains sensitive information and is only needed on your PostgreSQL instance. +{{% /notice %}} + +## Configure Sensu to use certificate authentication with PostgreSQL + +{{% notice note %}} +**NOTE**: The Sensu backend uses the libpq library to make connections to PostgreSQL. +This library [supports a number of environment variables](https://www.postgresql.org/docs/current/libpq-envars.html) that can be injected into the PostgreSQL data source name (DSN) and are loaded at runtime using the system's environment variable file. +These environment variables allow you to customize the Sensu backend's PostgreSQL DSN construction to suit your needs. +{{% /notice %}} + +Working from your Sensu backend, follow these steps to configure Sensu to use certificate authentication with PostgreSQL: + +1. Define the environment variables that tell the Sensu backend to use a certificate to authenticate to PostgreSQL: + + {{< language-toggle >}} + + {{< code shell "RHEL family" >}} +echo 'PGUSER=sensu +PGSSLMODE="verify-full" +PGSSLCERT="/etc/sensu/tls/sensu.pem" +PGSSLKEY="/etc/sensu/tls/sensu-key.pem" +PGSSLROOTCERT="/etc/sensu/tls/ca.pem"' | sudo tee /etc/sysconfig/sensu-backend +{{< /code >}} + + {{< code shell "Debian family" >}} +echo 'PGUSER=sensu +PGSSLMODE="verify-full" +PGSSLCERT="/etc/sensu/tls/sensu.pem" +PGSSLKEY="/etc/sensu/tls/sensu-key.pem" +PGSSLROOTCERT="/etc/sensu/tls/ca.pem"' | sudo tee /etc/default/sensu-backend +{{< /code >}} + +{{< /language-toggle >}} + + Do not restart your backend to load the environment variables yet. + +2. Adjust the Sensu datastore connection with sensuctl: + + {{< code shell >}} + +echo 'type: PostgresConfig +api_version: store/v1 +metadata: + name: sensu_postgres +spec: + dsn: "postgresql://sensu:mypass@postgres.example.com:5432/sensu_events" + pool_size: 20 + strict: false' | sudo tee postgresconfig.yml + +sensuctl create -f postgresconfig.yml + +{{< /code >}} + + {{% notice note %}} +**NOTE**: Setting `strict: false` in the configuration helps ensure that the Sensu backend will remain active and able to process events even in case of a configuration mistake. +{{% /notice %}} + +3. Confirm that the connection to your PostgreSQL instance is healthy: + + {{< code shell >}} +curl http://localhost:8080/health +{{< /code >}} + + The response should be similar to this example, with `true` values for both `Active` and `Healthy`: + + {{< code text >}} +{ + "Alarms": null, + "ClusterHealth": [ + { + "MemberID": 13217573501179607000, + "MemberIDHex": "b76e4111d26d35e2", + "Name": "sensu.example.com", + "Err": "", + "Healthy": true + } + ], + "Header": { + "cluster_id": 11959078708079102000, + "member_id": 6370351775894128000, + "raft_term": 4242 + }, + "PostgresHealth": [ + { + "Name": "sensu_postgres", + "Active": true, + "Healthy": true + } + ] +} +{{< /code >}} + + Now that you've confirmed that the Sensu backend can connect to your PostgreSQL instance, you can configure PostgreSQL to use TLS. + +### Configure PostgreSQL to use TLS + +To configure your PostgreSQL instance to use TLS: + +1. Copy your PostgreSQL certificate files from your Sensu backend. +From the `/etc/sensu/tls` directory, run: + + {{< code shell >}} +scp postgres.example.com* postgres.example.com:/home/user +scp ca.pem postgres.example.com:/home/user +{{< /code >}} + +2. From your PostgreSQL instance, create a new directory and move your PostgreSQL certificate files from your Sensu backend: + + {{< language-toggle >}} + + {{< code shell "RHEL family" >}} +sudo mkdir /var/lib/pgsql/14/data/tls +cd /var/lib/pgsql/14/data/tls +cp /home/user/postgres.example.com* /var/lib/pgsql/14/data/tls/ +cp /home/user/ca.pem /var/lib/pgsql/14/data/tls/ +chown -R postgres:postgres /var/lib/pgsql/14/data +{{< /code >}} + + {{< code shell "Debian family" >}} +sudo mkdir /etc/postgresql/14/main/tls +cd /etc/postgresql/14/main/tls +cp /home/user/postgres.example.com* /etc/postgresql/14/main/tls/ +cp /home/user/ca.pem /etc/postgresql/14/main/tls/ +chown -R postgres:postgres /etc/postgresql/14/main/ +{{< /code >}} + +{{< /language-toggle >}} + +3. Open the PostgreSQL configuration file `postgresql.conf` in your code editor and edit the following lines to enable TLS: + + {{< language-toggle >}} + + {{< code shell "RHEL family" >}} +# vim /var/lib/pgsql/14/data/postgresql.conf + +# - SSL - + +ssl = on +ssl_ca_file = '/var/lib/pgsql/14/data/tls/ca.pem' +ssl_cert_file = '/var/lib/pgsql/14/data/tls/postgres.example.com.pem' +ssl_key_file = '/var/lib/pgsql/14/data/tls/postgres.example.com-key.pem' +{{< /code >}} + + {{< code shell "Debian family" >}} +# vim /etc/postgresql/14/main/postgresql.conf + +# - SSL - + +ssl = on +ssl_ca_file = '/etc/postgresql/14/main/tls/ca.pem' +ssl_cert_file = '/etc/postgresql/14/main/tls/postgres.example.com.pem' +ssl_key_file = '/etc/postgresql/14/main/tls/postgres.example.com-key.pem' +{{< /code >}} + + {{< / language-toggle >}} + + Save your changes and close the file. + +4. Open the `pg_hba.conf` file in your Linux distribution and add the following lines to configure host-based authentication to accept certificates only when accessing the `sensu_events` database: + + {{< language-toggle >}} + + {{< code shell "RHEL family" >}} + +# /var/lib/pgsql/14/data/pg_hba.conf (file location) + +# Prevent "postgres" superuser login via a certificate +hostssl all postgres ::/0 reject +hostssl all postgres 0.0.0.0/0 reject + +# Rules for Sensu DB connection +hostssl sensu_events sensu 0.0.0.0/0 cert +{{< /code >}} + + {{< code shell "Debian family" >}} + +# /etc/postgresql/14/main/pg_hba.conf (file location) + +# Prevent "postgres" superuser login via a certificate +hostssl all postgres ::/0 reject +hostssl all postgres 0.0.0.0/0 reject + +# Rules for Sensu DB connection +hostssl sensu_events sensu 0.0.0.0/0 cert +{{< /code >}} + +{{< /language-toggle >}} + + Take care to add the new lines in the positions shown in the following example: + + {{< figure src="/images/go/secure_postgres/config_cert_auth.png" alt="Correct positions for new lines in pg_hba.conf file" link="/images/go/secure_postgres/config_cert_auth.png" target="_blank" >}} + +5. Restart PostgreSQL: + + {{< language-toggle >}} + + {{< code shell "RHEL family" >}} +sudo systemctl restart postgresql-14.service +{{< /code >}} + + {{< code shell "Debian family" >}} +sudo systemctl restart postgresql.service +{{< /code >}} + +{{< /language-toggle >}} + +Now that you've configured PostgreSQL to use TLS and your Sensu user is required to authenticate with a certificate, complete one final step to ensure that the Sensu backend uses the environment variables set earlier in this guide when constructing the PostgreSQL DSN. + +### Validate Sensu backend configuration for PostgreSQL + +After restarting PostgreSQL, the Sensu user should ***not*** be able to communicate with PostgreSQL because it requires certificate authentication for the `sensu_events` database. +Run: + +{{< code shell >}} +curl http://localhost:8080/health +{{< /code >}} + +The response should include `false` values for PostgresHealth.Active and PostgresHealth.Healthy: + +{{< code json >}} +{ + "Alarms": null, + "ClusterHealth": [ + { + "MemberID": 13217573501179607000, + "MemberIDHex": "b76e4111d26d35e2", + "Name": "sensu.example.com", + "Err": "", + "Healthy": true + } + ], + "Header": { + "cluster_id": 11959078708079102000, + "member_id": 6370351775894128000, + "raft_term": 4242 + }, + "PostgresHealth": [ + { + "Name": "sensu_postgres", + "Active": false, + "Healthy": false + } + ] +} +{{< /code >}} + +For Sensu to use certificate authentication, you must restart the backend service to load the environment variables set previously: + +{{< code shell >}} +sudo systemctl restart sensu-backend.service +{{< /code >}} + +To validate that your Sensu backend can reach PostgreSQL and authenticate after restarting, run the following command: + +{{< code shell >}} +curl http://localhost:8080/health +{{< /code >}} + +The response should be similar to the following example. +If the `Active` and `Healthy` attributes are not **both** `true`, stop and troubleshoot your connection to PostgreSQL *before* you continue: + +{{< code json >}} +{ + "Alarms": null, + "ClusterHealth": [ + { + "MemberID": 13217573501179607000, + "MemberIDHex": "b76e4111d26d35e2", + "Name": "sensu.example.com", + "Err": "", + "Healthy": true + } + ], + "Header": { + "cluster_id": 11959078708079102000, + "member_id": 6370351775894128000, + "raft_term": 4242 + }, + "PostgresHealth": [ + { + "Name": "sensu_postgres", + "Active": true, + "Healthy": true + } + ] +} +{{< /code >}} + +### Optional step: Require PostgreSQL as event store + +To force Sensu to always use PostgreSQL as the event store instead of falling back to etcd if PostgreSQL becomes unavailable, set `strict: true` in your PostgreSQL configuration file. + +**If you prefer to use etcd as a fallback, skip this step.** +Using etcd as a fallback may result in disk quota alarms and etcd unavailability, especially in environments with a large number of events. + +To set `strict: true` in your PostgreSQL configuration file, run: + +{{< code shell >}} +echo 'type: PostgresConfig +api_version: store/v1 +metadata: + name: sensu_postgres +spec: + dsn: "postgresql://postgres.example.com:5432/sensu_events" + pool_size: 20 + strict: true' | sudo tee postgresconfig.yml + +sensuctl create -f postgresconfig.yml +{{< /code >}} + +Your backend will now use PostgreSQL exclusively for storing events. + +To view your PostgresConfig definition and confirm that it is updated, run: + +{{< code shell >}} +sensuctl dump store/v1.PostgresConfig --format yaml +{{< /code >}} + + +[1]: ../secure-sensu +[2]: https://github.com/cloudflare/cfssl +[3]: ../generate-certificates +[4]: ../scale-event-storage diff --git a/content/sensu-go/6.12/operations/deploy-sensu/secure-sensu.md b/content/sensu-go/6.12/operations/deploy-sensu/secure-sensu.md new file mode 100644 index 0000000000..7850c810e0 --- /dev/null +++ b/content/sensu-go/6.12/operations/deploy-sensu/secure-sensu.md @@ -0,0 +1,390 @@ +--- +title: "Secure Sensu" +linkTitle: "Secure Sensu" +guide_title: "Secure Sensu" +type: "guide" +description: "Secure components like the Sensu API and web UI and agent-to-server communication and configure agent mTLS authentication to make Sensu production-ready." +weight: 60 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: deploy-sensu +--- + +As with any piece of software, it is critical to minimize any attack surface the software exposes. +Sensu is no different. + +This reference describes the components you need to secure to make Sensu production-ready, including etcd peer communication, the Sensu API and web UI, and Sensu agent-to-server communication. +It also describes agent mutual transport layer security (mTLS) authentication, which is required for [secrets management][1]. + +Before you can secure Sensu, you must [generate the certificates][12] you will need. +After you generate certificates, follow this reference to secure Sensu for production. + +{{% notice note %}} +**NOTE**: As of [Go 1.15](https://golang.google.cn/doc/go1.15#commonname), certificates must include their Common Name (CN) as a Subject Alternative Name (SAN) field. +To prevent connection errors, follow [Generate certificates](../generate-certificates/) to make sure your certificates' SAN fields include their CNs. +{{% /notice %}} + +## Secure etcd peer communication + +{{% notice warning %}} +**WARNING**: You must update the default configuration for Sensu's embedded etcd with an explicit, non-default configuration to secure etcd communication in transit. +If you do not properly configure secure etcd communication, your Sensu configuration will be vulnerable to unauthorized manipulation via etcd client connections. +{{% /notice %}} + +To properly secure etcd communication, replace the default configuration option values in your backend store configuration in `/etc/sensu/backend.yml` as follows: + +1. Replace the placeholder with the path to your certificate and key for the `etcd-cert-file` and `etcd-key-file` to secure client communication: +{{< code yml >}} +etcd-cert-file: "/etc/sensu/tls/backend-1.example.com.pem" +etcd-key-file: "/etc/sensu/tls/backend-1-key.example.com.pem" +{{< /code >}} + +2. Replace the placeholder with the path to your certificate and key for the `etcd-peer-cert-file` and `etcd-peer-key-file` to secure cluster communication: +{{< code yml >}} +etcd-peer-cert-file: "/etc/sensu/tls/backend-1.example.com.pem" +etcd-peer-key-file: "/etc/sensu/tls/backend-1-key.example.com.pem" +{{< /code >}} + +3. Replace the placeholder with the path to your `ca.pem` certificate for the `etcd-trusted-ca-file` and `etcd-peer-trusted-ca-file` to secure communication with the etcd client server and between etcd cluster members: +{{< code yml >}} +etcd-trusted-ca-file: "/etc/sensu/tls/ca.pem" +etcd-peer-trusted-ca-file: "/etc/sensu/tls/ca.pem" +{{< /code >}} + +4. Add non-default values for `etcd-listen-client-urls`, `etcd-listen-peer-urls`, and `etcd-initial-advertise-peer-urls`: +{{< code yml >}} +etcd-listen-client-urls: "https://localhost:2379" +etcd-listen-peer-urls: "https://localhost:2380" +etcd-advertise-client-urls: "https://localhost:2379" +etcd-initial-advertise-peer-urls: "https://localhost:2380" +{{< /code >}} + + {{% notice note %}} +**NOTE**: If you are securing a [cluster](../cluster-sensu), use your backend node IP address instead of `localhost` in the non-default values for `etcd-listen-client-urls`, `etcd-listen-peer-urls`, and `etcd-initial-advertise-peer-urls`. +{{% /notice %}} + +5. Set `etcd-client-cert-auth` and `etcd-peer-client-cert-auth` to `true` to ensure that etcd only allows connections from clients and peers that present a valid, trusted certificate: +{{< code yml >}} +etcd-client-cert-auth: "true" +etcd-peer-client-cert-auth: "true" +{{< /code >}} + + Because etcd does not require authentication by default, you must set the `etcd-client-cert-auth` and `etcd-peer-client-cert-auth` configuration options to `true` to secure Sensu's embedded etcd datastore against unauthorized access. + +{{% notice note %}} +**NOTE**: The [Sensu backend reference](../../../observability-pipeline/observe-schedule/backend/#datastore-and-cluster-configuration) includes more information about each etcd store configuration option. +{{% /notice %}} + +## Secure the Sensu agent API, HTTP API, and web UI + +The Sensu Go agent API, HTTP API, and web UI use a common stanza in `/etc/sensu/backend.yml` to provide the certificate, key, and CA file needed to provide secure communication. + +{{% notice note %}} +**NOTE**: By changing these configuration options, the server will communicate using transport layer security (TLS) and expect agents that connect to it to use the WebSocket secure protocol. +For communication to continue, you must complete the configuration in this section **and** in the [Sensu agent-to-server communication](#secure-sensu-agent-to-server-communication) section. +{{% /notice %}} + +Configure the following backend secure sockets layer (SSL) attributes in `/etc/sensu/backend.yml`: + +1. Replace the placeholders with the paths to your CA root, backend certificate, and backend key files for the `trusted-ca-file`, `cert-file`, and `key-file` configuration options: +{{< code yml >}} +trusted-ca-file: "/etc/sensu/tls/ca.pem" +cert-file: "/etc/sensu/tls/backend-1.example.com.pem" +key-file: "/etc/sensu/tls/backend-1-key.example.com.pem" +{{< /code >}} + +2. Set the `insecure-skip-tls-verify` configuration option to `false`: +{{< code yml >}} +insecure-skip-tls-verify: false +{{< /code >}} + +3. When you provide these cert-file and key-file configuration options, the agent WebSocket API and HTTP API will serve requests over SSL/TLS (https). +For this reason, you must also specify `https://` schema for the `api-url` configuration option for backend API configuration: +{{< code yml >}} +api-url: "https://localhost:8080" +{{< /code >}} + +Restart the `sensu-backend` service: + +{{< code shell >}} +sudo systemctl restart sensu-backend +{{< /code >}} + +After you restart the `sensu-backend` service, the configuration options will load and you will able to access the web UI at https://localhost:3000. +Configuring these options will also ensure that agents can communicate securely. + +{{% notice note %}} +**NOTE**: The [Sensu backend reference](../../../observability-pipeline/observe-schedule/backend/#security-configuration) includes more information about each API and web UI security configuration option. +{{% /notice %}} + +### Specify a separate web UI certificate and key + +You can use the same certificates and keys to secure etcd, the HTTP API, and the web UI. +However, if you prefer, you can use a separate certificate and key for the web UI (for example, a commercially purchased certificate and key). + +To do this, add the `dashboard-cert-file` and `dashboard-key-file` configuration options for backend SSL configuration in `/etc/sensu/backend.yml`: + +{{< code yml >}} +dashboard-cert-file: "/etc/sensu/tls/separate-webui-cert.pem" +dashboard-key-file: "/etc/sensu/tls/separate-webui-key.pem" +{{< /code >}} + +{{% notice note %}} +**NOTE**: If you do not specify a separate certificate and key for the web UI with `dashboard-cert-file` and `dashboard-key-file`, Sensu uses the certificate and key specified for the `cert-file` and `key-file` configuration options for the web UI. +The [Sensu backend reference](../../../observability-pipeline/observe-schedule/backend/#web-ui-configuration) includes more information about the `dashboard-cert-file` and `dashboard-key-file` web UI configuration options. +{{% /notice %}} + +## Secure Sensu agent-to-server communication + +{{% notice note %}} +**NOTE**: If you change the agent configuration to communicate via WebSocket Secure protocol, the agent will no longer communicate over a plaintext connection. +For communication to continue, you must complete the steps in this section **and** [secure the Sensu agent API, HTTP API, and web UI](#secure-the-sensu-agent-api-http-api-and-web-ui). +{{% /notice %}} + +By default, an agent uses the insecure `ws://` transport. +Here's an example for agent configuration in `/etc/sensu/agent.yml`: + +{{< code yml >}} +backend-url: + - "ws://127.0.0.1:8081" +{{< /code >}} + +To use WebSocket over SSL/TLS (wss), change the `backend-url` value to the `wss://` schema in `/etc/sensu/agent.yml`: + +{{< code yml >}} +backend-url: + - "wss://127.0.0.1:8081" +{{< /code >}} + +The agent will connect to Sensu backends over wss. +Remember, if you change the configuration to wss, plaintext communication will not be possible. + +You can also provide a trusted CA root certificate file as part of the agent configuration (named `ca.pem` in the example in [Generate certificates][4]). +If you will start the agent via `sensu-agent start`, pass the `--trusted-ca-file` flag with the start command. +Otherwise, include the `trusted-ca-file` configuration option in the agent configuration in `/etc/sensu/agent.yml`: + +{{< code yml>}} +trusted-ca-file: "/etc/sensu/tls/ca.pem" +{{< /code >}} + +{{% notice note %}} +**NOTE**: If you are creating a Sensu cluster, every cluster member needs to be present in the configuration. +Read [Run a Sensu cluster](../cluster-sensu/) for more information about how to configure agents for a clustered configuration. +{{% /notice %}} + +## Optional: Configure Sensu agent mTLS authentication + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access client mutual transport layer security (mTLS) authentication in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} + +By default, Sensu agents require username and password authentication to communicate with Sensu backends. +For Sensu's [default user credentials][2] and details about configuring Sensu role-based access control (RBAC), read the [RBAC reference][3]. + +Alternatively, Sensu agents can use mTLS for authenticating to the backend WebSocket transport. +When agent mTLS authentication is enabled, agents do not need to send password credentials to backends when they connect. +To use [secrets management][1], Sensu agents must be secured with mTLS. +In addition, when using mTLS authentication, agents do not require an explicit user in Sensu. +Sensu agents default to authenticating as the [`agent` user][2] and using permissions granted to the `system:agents` group by the `system:agents` cluster role and cluster role binding. + +You can still bind agents to a specific user when the `system:agents` group is problematic. +For this use case, create a user that matches the Common Name (CN) of the agent's certificate. + +{{% notice note %}} +**NOTE**: Sensu agents need to be able to create events in the agent's namespace. +To ensure that agents with incorrect CN fields can't access the backend, remove the default `system:agents` group. +{{% /notice %}} + +For example, if you have a certificate named `client.pem`, you can run the following command to view the certificate's CN with openssl: + +{{< code bash >}} +openssl x509 -in client.pem -text -noout +{{< /code >}} + +The response should be similar to this example: + +{{< code text >}} +Certificate: + Data: + Version: 3 (0x2) + Serial Number: + 37:57:7b:04:1d:67:63:7b:ff:ae:39:19:5b:55:57:80:41:3c:ec:ff + Signature Algorithm: sha256WithRSAEncryption + Issuer: CN = CA + Validity + Not Before: Sep 26 18:58:00 2019 GMT + Not After : Sep 24 18:58:00 2024 GMT + Subject: CN = client +... +{{< /code >}} + +The `Subject:` field indicates the certificate's CN is `client`, so to bind the agent to a particular user in Sensu, create a user called `client`. + +To enable agent mTLS authentication: + +1. Create and distribute a new Certificate Authority (CA) root certificate and new agent and backend certificates and keys according to the [Generate certificates][12] guide. + +2. Add the following configuration options and values to the backend configuration `/etc/sensu/backend.yml`: +{{< code yml >}} +agent-auth-cert-file: "/etc/sensu/tls/backend-1.example.com.pem" +agent-auth-key-file: "/etc/sensu/tls/backend-1-key.example.com.pem" +agent-auth-trusted-ca-file: "/etc/sensu/tls/ca.pem" +{{< /code >}} + +3. Add the following configuration options and values to the agent configuration in `/etc/sensu/agent.yml`: +{{< code yml >}} +cert-file: "/etc/sensu/tls/agent.pem" +key-file: "/etc/sensu/tls/agent-key.pem" +trusted-ca-file: "/etc/sensu/tls/ca.pem" +{{< /code >}} + +You can use certificates for authentication that are distinct from other communication channels used by Sensu, like etcd or the API. +However, deployments can also use the same certificates and keys for etcd peer and client communication, the HTTP API, and agent authentication without issues. + +### Certificate revocation check + +The Sensu backend checks certificate revocation list (CRL) and Online Certificate Status Protocol (OCSP) endpoints for agent mTLS, etcd client, and etcd peer connections whose remote sides present X.509 certificates that provide CRL and OCSP revocation information. + +## Optional: Configure Sensu for FIPS compliance + +Sensu provides a Linux amd64 OpenSSL-linked build that supports the Federal Information Processing Standard (FIPS) for Federal Risk and Authorization Management Program (FedRAMP) compliance. + +The Sensu build with FIPS-mode configuration options is linked with the FIPS 140-2 validated cryptographic library. +Sensu builds comply with the FIPS-mode kernel option to enforce FIPS systemwide in Red Hat Enterprise Linux (RHEL). +[Contact Sensu][13] to request the build with FIPS support. + +Sensu backends and agents will work on systems with FIPS kernel mode if the `require-fips` configuration option is set to `true` in the [backend][14] and [agent][15] configuration files. +Sensu backends and agents that have `require-fips` enabled will *not* work on systems without FIPS kernel mode. + +Sensu backends on systems with FIPS kernel mode will work with PostgreSQL on systems with FIPS kernel mode. +For PostgreSQL on systems *without* FIPS kernel mode, Sensu backends with FIPS kernel mode will work as long as the PostgreSQL system supports FIPS-compliant ciphers/cipher suites. + +Sensu agents and sensuctl on systems with and without FIPS kernel mode can connect to Sensu backends on systems with FIPS kernel mode. + +### Configuration example for embedded etcd + +To configure the Sensu backend for FIPS mode with embedded etcd, update the backend configuration file at `/etc/sensu/backend.yml` to use the following settings: + +{{< code shell >}} +# fips configuration +require-fips: true + +# etcd configuration +etcd-listen-client-urls: "https://localhost:2379" +etcd-listen-peer-urls: "https://localhost:2380" +etcd-advertise-client-urls: "https://localhost:2379" +etcd-initial-advertise-peer-urls: "https://localhost:2380" + +# etcd client tls configuration +etcd-client-cert-auth: "true" +etcd-trusted-ca-file: "/etc/sensu/tls/ca.pem" +etcd-cert-file: "/etc/sensu/tls/centos-7-fips-1-backend.pem" +etcd-key-file: "/etc/sensu/tls/centos-7-fips-1-backend-key.pem" + +# etcd peer tls configuration +etcd-peer-client-cert-auth: "true" +etcd-peer-trusted-ca-file: "/etc/sensu/tls/ca.pem" +etcd-peer-cert-file: "/etc/sensu/tls/centos-7-fips-1-backend.pem" +etcd-peer-key-file: "/etc/sensu/tls/centos-7-fips-1-backend-key.pem" + +# api configuration +api-url: "https://localhost:8080" + +# api tls configuration +insecure-skip-tls-verify: false +trusted-ca-file: "/etc/sensu/tls/ca.pem" +cert-file: "/etc/sensu/tls/centos-7-fips-1-backend.pem" +key-file: "/etc/sensu/tls/centos-7-fips-1-backend-key.pem" +{{< /code >}} + +{{% notice note %}} +**NOTE**: If you are securing a [cluster](../cluster-sensu), use your backend node IP address instead of `localhost`. +{{% /notice %}} + +### Configuration example for external etcd + +To configure the Sensu backend for FIPS mode with external etcd, update the backend configuration file at `/etc/sensu/backend.yml` to use the following settings: + +{{< code shell >}} +# fips configuration +require-fips: true + +# etcd configuration +etcd-trusted-ca-file: "/etc/sensu/tls/ca.pem" +etcd-cert-file: "/etc/sensu/tls/centos-7-fips-1-backend.pem" +etcd-key-file: "/etc/sensu/tls/centos-7-fips-1-backend-key.pem" +etcd-client-urls: "https://localhost:2379" +no-embed-etcd: true + +# api configuration +api-url: "https://localhost:8080" + +# api tls configuration +insecure-skip-tls-verify: false +trusted-ca-file: "/etc/sensu/tls/ca.pem" +cert-file: "/etc/sensu/tls/centos-7-fips-1-backend.pem" +key-file: "/etc/sensu/tls/centos-7-fips-1-backend-key.pem" +{{< /code >}} + +Use the following settings in your etcd configuration: + +{{< code shell >}} +name: "centos-7-fips-1" +data-dir: "/var/lib/etcd-external" +auto-compaction-mode: "revision" +auto-compaction-retention: "2" + +# cluster config +initial-cluster-token: "sup3rs3cr3t" +initial-cluster: "centos-7-fips-1=https://centos-7-fips-1:2380" +initial-cluster-state: "new" + +# etcd configuration +listen-client-urls: "https://localhost:2379" +listen-peer-urls: "https://localhost:2380" +advertise-client-urls: "https://localhost:2379" +initial-advertise-peer-urls: "https://localhost:2380" + +# etcd client tls configuration +client-transport-security: + client-cert-auth: true + trusted-ca-file: /etc/etcd/tls/ca.pem + cert-file: /etc/etcd/tls/centos-7-fips-1-backend.pem + key-file: /etc/etcd/tls/centos-7-fips-1-backend-key.pem + auto-tls: false + +# etcd peer tls configuration +peer-transport-security: + client-cert-auth: true + trusted-ca-file: /etc/etcd/tls/ca.pem + cert-file: /etc/etcd/tls/centos-7-fips-1-backend.pem + key-file: /etc/etcd/tls/centos-7-fips-1-backend-key.pem + auto-tls: false +{{< /code >}} + +{{% notice note %}} +**NOTE**: If you are securing a [cluster](../cluster-sensu), use your backend node IP address instead of `localhost`. +{{% /notice %}} + +## Next step: Run a Sensu cluster + +Well done! +Your Sensu installation should now be secured with TLS. +The last step before you deploy Sensu is to [set up a Sensu cluster][10]. + + +[1]: ../../manage-secrets/secrets-management/ +[2]: ../../control-access/rbac/#default-users +[3]: ../../control-access/rbac/ +[4]: ../generate-certificates/#create-a-certificate-authority-ca +[6]: https://etcd.io/docs/latest/op-guide/security/ +[9]: https://github.com/cloudflare/cfssl +[10]: ../cluster-sensu/ +[12]: ../generate-certificates/ +[13]: https://sensu.io/contact +[14]: ../../../observability-pipeline/observe-schedule/backend/#fips-openssl +[15]: ../../../observability-pipeline/observe-schedule/agent/#fips-openssl diff --git a/content/sensu-go/6.12/operations/deploy-sensu/use-federation.md b/content/sensu-go/6.12/operations/deploy-sensu/use-federation.md new file mode 100644 index 0000000000..8e2d664955 --- /dev/null +++ b/content/sensu-go/6.12/operations/deploy-sensu/use-federation.md @@ -0,0 +1,443 @@ +--- +title: "Multi-cluster visibility with federation" +linkTitle: "Reach Multi-cluster Visibility" +guide_title: "Multi-cluster visibility with federation" +type: "guide" +description: "Access and manage resources across multiple clusters via the web UI and mirror changes in one cluster to follower clusters with Sensu's federation features." +weight: 80 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: deploy-sensu +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access federation in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} + +Sensu's [enterprise/federation/v1 API endpoints][1] allow you to register external clusters, gain single-pane-of-glass visibility into the health of your infrastructure and services across multiple distinct Sensu instances within the web UI, and mirror your changes in one cluster to follower clusters. +This is useful when you want to provide a single entry point for Sensu users who need to manage monitoring across multiple distinct physical data centers, cloud regions, or providers. + +{{< figure src="/images/go/use_federation/federation_switcher_660.gif" alt="Animated demonstration of federated views in Sensu Web UI" link="/images/go/use_federation/federation_switcher_660.gif" target="_blank" >}} + +After you configure federation, you can also create, update, and delete clusters using sensuctl [create][5], [edit][6], and [delete][7] commands. + +Federation is not enabled by default. +You must create a cluster resource for the federation cluster and [register it][14]. +Only cluster administrators can register a new cluster, but every user can [query the list of clusters][11]. + +Complete federation of multiple Sensu instances relies on a combination of features: + +| Feature | Purpose in federation | +|-------------------------------------|--------------------------------------------------------------------| +| JSON Web Token (JWT) authentication | Cross-cluster token authentication using asymmetric key encryption | +| etcd replicators | Replicate RBAC policy across clusters and namespaces | +| Federation Gateway and APIs | Configure federation access for cross-cluster visibility in web UI | + +Follow the example in this guide to configure these features. +The example assumes you wish to federate three named Sensu clusters: + +| Cluster name | Hostname | +|--------------|-----------------------| +| `gateway` | sensu.gateway.example.com | +| `alpha` | sensu.alpha.example.com | +| `beta` | sensu.beta.example.com | + +The `gateway` cluster will be the entry point for operators to manage Sensu resources in the `alpha` and `beta` clusters. +This guide assumes a single sensu-backend in each cluster, but named clusters composed of multiple sensu-backends are supported. + +This diagram depicts the federation relationship documented in this guide: + +{{< figure src="/images/go/use_federation/example_federation.png" alt="Diagram depicting this guide's example federation architecture" link="/images/go/use_federation/example_federation.png" target="_blank" >}} + + +Complete the steps in this guide to browse events, entities, checks, and other resources in the `gateway`, `alpha`, and `beta` clusters from the `gateway` cluster web UI. + +## Requirements + +Because federation depends on communication with multiple disparate clusters, working TLS is required for successful federated operation. + +To ensure that cluster members can validate each other, certificates for each cluster member should include the IP addresses or hostnames specified in the values of sensu-backend `etcd-advertise-client-urls`, `etcd-advertise-peer-urls`, and `etcd-initial-advertise-peer-urls` parameters. +In addition to the certificate's [Common Name (CN)][15], [Subject Alternative Names (SANs)][16] are also honored for validation. + +{{% notice note %}} +**NOTE**: As of [Go 1.15](https://golang.google.cn/doc/go1.15#commonname), certificates must include their CN as an SAN field. +To prevent connection errors, follow [Generate certificates](../generate-certificates/) to make sure your certificates' SAN fields include their CNs. +{{% /notice %}} + +To continue with this guide, make sure you have the required TLS credentials in place: + +* A PEM-formatted X.509 certificate and corresponding private key copied to each cluster member. +* A corresponding certificate authority (CA) certificate chain copied to each cluster member. + +If you don't have existing infrastructure for issuing certificates, read [Generate certificates][13] for our recommended self-signed certificate issuance process. + +This prerequisite extends to configuring the following Sensu backend etcd parameters: + +| Backend property | Description | +|------------------------------|-------------| +| `etcd-cert-file` | Path to certificate used for TLS on etcd client/peer communications (for example, `/etc/sensu/tls/backend-1.example.com.pem`. | +| `etcd-key-file` | Path to key corresponding with `etcd-cert-file` certificate (for example, `/etc/sensu/tls/backend-1-key.example.com.pem`. | +| `etcd-trusted-ca-file` | Path to CA certificate chain file (for example, `/etc/sensu/tls/ca.pem`. This CA certificate chain must be usable to validate certificates for all backends in the federation. | +| `etcd-client-cert-auth` | Enforces certificate validation to authenticate etcd replicator connections. Set to `true` to secure etcd communication. | +| `etcd-advertise-client-urls` | List of https URLs to advertise for etcd replicators, accessible by other backends in the federation (for example, `https://sensu.beta.example.com:2379`). | +| `etcd-listen-client-urls` | List of https URLs to listen on for etcd replicators (for example, `https://0.0.0.0:2379` to listen on port 2379 across all ipv4 interfaces). | + +{{% notice warning %}} +**WARNING**: You *must* provide an explicit, non-default etcd configuration to secure etcd communication in transit. +If you do not properly configure secure etcd communication, your Sensu configuration will be vulnerable to unauthorized manipulation via etcd client connections.

    +This includes providing non-default values for the `etcd-advertise-client-urls` and `etcd-listen-client-urls` backend parameters and creating a [certificate and key](../generate-certificates/) for the `etcd-cert-file` and `etcd-key-file` values. +The default values are not suitable for use under federation. +{{% /notice %}} + +## Configure shared token signing keys + +Whether federated or standalone, Sensu backends issue JSON Web Tokens (JWTs) to users upon successful authentication. +These tokens include a payload that describes the username and group affiliations. +The payload is used to determine permissions based on the configured RBAC policy. + +In a federation of Sensu backends, each backend needs to have the same public/private key pair. +These asymmetric keys are used to crypotgraphically vouch for the user's identity in the JWT payload. +Using shared JWT keys enables clusters to grant users access to Sensu resources according to their local policies but without requiring user resources to be present uniformly across all clusters in the federation. + +By default, a Sensu backend automatically generates an asymmetric key pair for signing JWTs and stores it in the etcd database. +When configuring federation, you must generate keys as files on disk so they can be copied to all backends in the federation. + +1. Use the `openssl` command line tool to generate a P-256 elliptic curve private key: +{{< code shell >}} +openssl ecparam -genkey -name prime256v1 -noout -out jwt_private.pem +{{< /code >}} + +2. Generate a public key from the private key: +{{< code shell >}} +openssl ec -in jwt_private.pem -pubout -out jwt_public.pem +{{< /code >}} + +3. Save the JWT keys in `/etc/sensu/certs` on each cluster backend. + +4. Add the `jwt-private-key-file` and `jwt-public-key-file` attributes in `/etc/sensu/backend.yml` and specify the paths to the JWT private and public keys: +{{< code yml >}} +jwt-private-key-file: /etc/sensu/certs/jwt_private.pem +jwt-public-key-file: /etc/sensu/certs/jwt_public.pem +{{< /code >}} + +5. Restart the Sensu backend so that your settings take effect: +{{< code shell >}} +sudo systemctl restart sensu-backend +{{< /code >}} + +## Add a user and a cluster role binding + +To test your configuration, provision a user and a cluster role binding in the `gateway` cluster. + +1. Confirm that sensuctl is configured to communicate with the `gateway` cluster: +{{< code shell >}} +sensuctl config view +{{< /code >}} + + The response will list the active configuration: +{{< code text >}} +=== Active Configuration +API URL: https://sensu.gateway.example.com:8080 +Namespace: default +Format: tabular +Username: admin +{{< /code >}} + +2. Create a `federation-viewer` user: +{{< code shell >}} +sensuctl user create federation-viewer --interactive +{{< /code >}} + +3. When prompted for username and groups, press enter. + +4. When prompted for password, enter a password for the `federation-viewer` user. +Make a note of the password you entered — you'll use it to log in to the web UI after you configure RBAC policy replication and registered clusters into your federation. + + This creates the following user: +{{< language-toggle >}} +{{< code text "YML" >}} +username: federation-viewer +disabled: false +{{< /code >}} +{{< code text "JSON" >}} +{ + "username": "federation-viewer", + "disabled": false +} +{{< /code >}} +{{< /language-toggle >}} + +5. Grant the `federation-viewer` user read-only access with a cluster role binding for the built-in `view` cluster role: +{{< code shell >}} +sensuctl cluster-role-binding create federation-viewer-readonly --cluster-role=view --user=federation-viewer +{{< /code >}} + + This command creates the following cluster role binding resource definition: +{{< language-toggle >}} +{{< code yml >}} +--- +type: ClusterRoleBinding +api_version: core/v2 +metadata: + created_by: admin + name: federation-viewer-readonly +spec: + role_ref: + name: view + type: ClusterRole + subjects: + - name: federation-viewer + type: User +{{< /code >}} +{{< code json >}} +{ + "type": "ClusterRoleBinding", + "api_version": "core/v2", + "metadata": { + "created_by": "admin", + "name": "federation-viewer-readonly" + }, + "spec": { + "role_ref": { + "name": "view", + "type": "ClusterRole" + }, + "subjects": [ + { + "name": "federation-viewer", + "type": "User" + } + ] + } +} +{{< /code >}} +{{< /language-toggle >}} + +## Create etcd replicators + +Etcd replicators use the [etcd make-mirror utility][12] for one-way replication of Sensu RBAC policy resources. +This allows you to centrally define RBAC policy on the `gateway` cluster and replicate RBAC resources to other clusters in the federation (`alpha` and `beta`), ensuring consistent permissions for Sensu users across multiple clusters via the `gateway` web UI. + +1. Configure one etcd replicator per cluster for each RBAC policy resource, across all namespaces, for each backend in the federation. +{{% notice note %}} +**NOTE**: Create a replicator for each resource type you want to replicate. +Replicating `namespace` resources will **not** replicate the Sensu resources that belong to those namespaces.

    +The etcd replicators reference includes [examples](../etcdreplicators#etcd-replicator-examples) you can follow for `Role`, `RoleBinding`, `ClusterRole`, and `ClusterRoleBinding` resources. +{{% /notice %}} + + In this example, the following etcd replicator resources will replicate ClusterRoleBinding resources from the `gateway` cluster to the two target clusters: +{{< language-toggle >}} +{{< code yml >}} +--- +api_version: federation/v1 +type: EtcdReplicator +metadata: + name: AlphaClusterRoleBindings +spec: + ca_cert: "/etc/sensu/certs/ca.pem" + cert: "/etc/sensu/certs/gateway.pem" + key: "/etc/sensu/certs/gateway-key.pem" + url: https://sensu.alpha.example.com:2379 + api_version: core/v2 + resource: ClusterRoleBinding + replication_interval_seconds: 30 +{{< /code >}} +{{< code json >}} +{ + "api_version": "federation/v1", + "type": "EtcdReplicator", + "metadata": { + "name": "AlphaClusterRoleBindings" + }, + "spec": { + "ca_cert": "/etc/sensu/certs/ca.pem", + "cert": "/etc/sensu/certs/gateway.pem", + "key": "/etc/sensu/certs/gateway-key.pem", + "url": "https://sensu.alpha.example.com:2379", + "api_version": "core/v2", + "resource": "ClusterRoleBinding", + "replication_interval_seconds": 30 + } +} +{{< /code >}} +{{< /language-toggle >}} +{{< language-toggle >}} +{{< code yml >}} +--- +api_version: federation/v1 +type: EtcdReplicator +metadata: + name: BetaClusterRoleBindings +spec: + ca_cert: "/etc/sensu/certs/ca.pem" + cert: "/etc/sensu/certs/gateway.pem" + key: "/etc/sensu/certs/gateway-key.pem" + url: https://sensu.beta.example.com:2379 + api_version: core/v2 + resource: ClusterRoleBinding + replication_interval_seconds: 30 +{{< /code >}} +{{< code json >}} +{ + "api_version": "federation/v1", + "type": "EtcdReplicator", + "metadata": { + "name": "BetaClusterRoleBindings" + }, + "spec": { + "ca_cert": "/etc/sensu/certs/ca.pem", + "cert": "/etc/sensu/certs/gateway.pem", + "key": "/etc/sensu/certs/gateway-key.pem", + "url": "https://sensu.beta.example.com:2379", + "api_version": "core/v2", + "resource": "ClusterRoleBinding", + "replication_interval_seconds": 30 + } +} +{{< /code >}} +{{< /language-toggle >}} + +2. Run `sensuctl config view` and verify that `sensuctl` is configured to talk to a `gateway` cluster API. +Reconfigure `sensuctl` if needed. + +3. Save the `AlphaClusterRoleBindings` and `BetaClusterRoleBindings` EtcdReplicator definitions to a file (for example, `etcdreplicators.yml` or `etcdreplicators.json`). + +4. Use `sensuctl create -f` to apply the `AlphaClusterRoleBindings` and `BetaClusterRoleBindings` EtcdReplicator definitions to the `gateway` cluster: +{{< language-toggle >}} +{{< code shell "YML" >}} +sensuctl create -f etcdreplicators.yml +{{< /code >}} +{{< code shell "JSON" >}} +sensuctl create -f etcdreplicators.json +{{< /code >}} +{{< /language-toggle >}} + +5. Verify that the EtcdReplicator resource is working as expected: reconfigure the sensuctl backend URL to communicate with the `alpha` and `beta` clusters and run the following command for each: +{{< code shell >}} +sensuctl cluster-role-binding info federation-viewer-readonly +{{< /code >}} + + The `federation-viewer-readonly` binding you created in the previous section should be listed in the output from each cluster: +{{< code text >}} +=== federation-viewer-readonly +Name: federation-viewer-readonly +Cluster Role: view +Subjects: + Users: federation-viewer +{{< /code >}} + +## Register clusters + +Clusters must be registered to become visible in the web UI. +Each registered cluster must have a name and a list of one or more cluster member URLs corresponding to the backend REST API. + +{{% notice note %}} +**NOTE**: Individual cluster resources may list the API URLs for a single stand-alone backend or multiple backends that are members of the same etcd cluster. +Creating a cluster resource that lists multiple backends that do not belong to the same cluster will result in unexpected behavior. +{{% /notice %}} + +### Register a single cluster + +With `sensuctl` configured for the `gateway` cluster, run `sensuctl create` on the yaml or JSON below to register cluster `alpha`: + +{{< language-toggle >}} + +{{< code yml >}} +api_version: federation/v1 +type: Cluster +metadata: + name: alpha +spec: + api_urls: + - https://sensu.alpha.example.com:8080 +{{< /code >}} + +{{< code json >}} +{ + "api_version": "federation/v1", + "type": "Cluster", + "metadata": { + "name": "alpha" + }, + "spec": { + "api_urls": [ + "https://sensu.alpha.example.com:8080" + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +### Register additional clusters + +With `sensuctl` configured for `gateway` cluster, run `sensuctl create` on the yaml or JSON below to register an additional cluster and define the name as `beta`: + +{{< language-toggle >}} + +{{< code yml >}} +api_version: federation/v1 +type: Cluster +metadata: + name: beta +spec: + api_urls: + - https://sensu.beta.example.com:8080 +{{< /code >}} + +{{< code json >}} +{ + "api_version": "federation/v1", + "type": "Cluster", + "metadata": { + "name": "beta" + }, + "spec": { + "api_urls": [ + "https://sensu.alpha.example.com:8080" + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +{{% notice note %}} +**NOTE**: When logging into the `gateway` cluster web UI, any namespaces, entities, events, and other resources specific to that cluster will be labeled as `local-cluster`. +{{% /notice %}} + +## Get a unified view of all your clusters in the web UI + +After you create clusters using enterprise/federation/v1 API endpoints, you can log in to the `gateway` Sensu web UI to view them as the `federation-viewer` user. +Use the namespace switcher to change between namespaces across federated clusters: + +{{< figure src="/images/go/use_federation/federation_namespace_switcher_660.gif" alt="Animated demonstration of federated views in Sensu Web UI" link="/images/go/use_federation/federation_namespace_switcher_660.gif" target="_blank" >}} + +Because the `federation-viewer` user is granted only permissions provided by the built-in `view` role, this user should be able to view all resources across all clusters but should not be able to make any changes. +If you haven't changed the permissions of the default `admin` user, that user should be able to view, create, delete, and update resources across all clusters. + +## What's next + +Learn more about configuring Sensu RBAC policies in the [RBAC reference][10] and one-way replication of RBAC resources in the [etcd replicators reference][17]. + +Read the backend reference for details about the [`jwt-private-key-file` and `jwt-public-key-file` attributes][4] used to crypotgraphically vouch for the user's identity in the JWT payload. + + +[1]: ../../../api/enterprise/federation/ +[3]: ../../control-access/use-apikeys/ +[4]: ../../../observability-pipeline/observe-schedule/backend#jwt-attributes +[5]: ../../../sensuctl/create-manage-resources/#create-resources +[6]: ../../../sensuctl/create-manage-resources/#update-resources +[7]: ../../../sensuctl/create-manage-resources/#delete-resources +[10]: ../../control-access/rbac/ +[11]: ../../../api/enterprise/federation/#get-all-clusters +[12]: https://github.com/etcd-io/etcd/blob/master/etcdctl/README.md#make-mirror-options-destination +[13]: ../generate-certificates/ +[14]: #register-a-single-cluster +[15]: https://support.dnsimple.com/articles/what-is-common-name/ +[16]: https://support.dnsimple.com/articles/what-is-ssl-san/ +[17]: ../etcdreplicators/ diff --git a/content/sensu-go/6.12/operations/maintain-sensu/_index.md b/content/sensu-go/6.12/operations/maintain-sensu/_index.md new file mode 100644 index 0000000000..740dd5106a --- /dev/null +++ b/content/sensu-go/6.12/operations/maintain-sensu/_index.md @@ -0,0 +1,49 @@ +--- +title: "Maintain Sensu" +description: "Read about how to maintain and troubleshoot your Sensu installation, including upgrading to the latest Sensu version." +product: "Sensu Go" +version: "6.12" +weight: 30 +layout: "single" +toc: true +menu: + sensu-go-6.12: + parent: operations + identifier: maintain-sensu +--- + +The Maintain Sensu category includes information to keep your Sensu installation up-to-date and running smoothly. + +## Upgrade or migrate + +Follow the [upgrade guide][1] for step-by-step instructions to upgrade to the latest version of Sensu from any earlier version. +The upgrade instructions include details about important changes between versions that could affect your upgrade and any special requirements to make sure your upgrade is successful. + +If you are still using Sensu Core or Sensu Enterprise, follow [Migrate from Sensu Core and Sensu Enterprise to Sensu Go][2] to upgrade to Sensu Go. +The migrate guide includes links to Sensu's migration resources and Core and Enterprise configuration translation tools, as well as instructions for [installing Sensu Go alongside your existing Sensu Core or Enterprise instance][3]. + +## Troubleshoot + +Use the Sensu [troubleshooting guide][4] to diagnose and resolve common problems, and read about [tuning options][11] for specific performance issues. +Learn how to read, configure, and find the [logs produced by Sensu services][6]. +Sensu log messages can help you identify and solve [backend startup errors][7] and [permissions issues][8]. + +The troubleshooting guide also describes how to [use Sensu handlers and filters to test and debug your observability pipeline][9] and diagnose problems related to [dynamic runtime assets][10]. + +## Manage license + +Read the [license reference][5] to learn how to activate your commercial license. +The license reference also explains how to view your license details and expiration date and find your current entity count and limits. + + +[1]: upgrade/ +[2]: migrate/ +[3]: migrate/#step-by-step-migration-instructions +[4]: troubleshoot/ +[5]: license/ +[6]: troubleshoot/#service-logging +[7]: troubleshoot/#sensu-backend-startup-errors +[8]: troubleshoot/#permission-issues +[9]: troubleshoot/#handlers-and-event-filters +[10]: troubleshoot/#dynamic-runtime-assets +[11]: tune/ diff --git a/content/sensu-go/6.12/operations/maintain-sensu/disaster-recovery.md b/content/sensu-go/6.12/operations/maintain-sensu/disaster-recovery.md new file mode 100644 index 0000000000..93a2b11544 --- /dev/null +++ b/content/sensu-go/6.12/operations/maintain-sensu/disaster-recovery.md @@ -0,0 +1,452 @@ +--- +title: "Restore your Sensu configuration for disaster recovery" +linkTitle: "Restore Sensu Configuration" +description: "Learn how to export and back up your Sensu resources and restore your Sensu configuration for disaster recovery (DR)." +weight: 35 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: maintain-sensu +--- + +This page explains how to restore your Sensu configuration for disaster recovery. +The disaster recovery processes include steps for creating backups of your Sensu configuration, but you must make backups *before* you need to use them. +Read [best practices for backups][2] for more information. + +The instructions for restoring Sensu assume that your primary Sensu deployment is down and you need to bring up a new one to take its place. + +## PostgreSQL + +This section explains how to back up your Sensu configuration for PostgreSQL rather than the PostgreSQL database. +In a Sensu deployment, PostgreSQL stores the last 21 check executions, which limits its use in disaster recovery scenarios. +As a best practice, we recommend a time series database (TSDB) for long-term event retention and storage. + +### Back up the Sensu configuration for PostgreSQL + +{{% notice note %}} +**NOTE**: This process uses [sensuctl dump](../../../sensuctl/back-up-recover/) to create backups. +When you export users with sensuctl dump, passwords are not included — you must add the [`password_hash`](../../../sensuctl/#generate-a-password-hash) or `password` attribute back to exported user definitions before you can restore users with sensuctl create. +Also, sensuctl create does not restore API keys from a sensuctl dump backup.

    +We suggest backing up API keys and users in a separate file that you can use as a reference for granting new API keys and adding the `password_hash` or `password` attribute to user definitions.

    For details about the sensuctl dump command, read [Back up and recover resources with sensuctl](../../../sensuctl/back-up-recover/). +{{% /notice %}} + +If you use PostgreSQL for your Sensu instance, follow these steps to create a backup of your Sensu configuration: + +1. Create a backup folder: + + {{< code shell >}} +mkdir backup +{{< /code >}} + +2. Export the PostgreSQL configuration: + + {{< code shell >}} +sensuctl dump store/v1.PostgresConfig \ +--format wrapped-json \ +--file backup/psql_config_backup.json +{{< /code >}} + +### Restore the Sensu configuration for PostgreSQL + +The instructions in this section assume that you already have a newly deployed Sensu instance (or instances in a cluster configuration) and a newly deployed PostgreSQL instance. + +To restore the PostgreSQL configuration for Sensu, follow these steps: + +1. Confirm that your new Sensu deployment is up and running: + + {{< code shell >}} +systemctl status sensu-backend +{{< /code >}} + + The response should indicate `active (running)`. + +2. Confirm that your new Sensu deployment is healthy: + + {{< code shell >}} +sensuctl cluster health +{{< /code >}} + +3. Restore the PostgreSQL configuration to activate the PostgreSQL event store: + + {{< code shell >}} +sensuctl create --file backup/psql_config_backup.json +{{< /code >}} + +## Etcd + +The etcd backup processes use the `etcdctl snapshot save` command. +For details about etcd snapshot and restore capabilities, read the [etcd disaster recovery documentation][5]. + +{{% notice warning %}} +**IMPORTANT**: Update the example values in these commands according to your Sensu configuration before running the commands. +{{% /notice %}} + +### Snapshot the Sensu etcd database + +Whether you're using the embedded version of etcd for Sensu or an external etcd instance, you must install etcdctl on the system you use to generate a snapshot. +Read the [etcd installation documentation][4] to install etcdctl. + +Run the following command to take a snapshot of Sensu's embedded etcd database: + +{{< language-toggle >}} + +{{< code shell "Command format" >}} +ETCD_API= etcdctl snapshot --endpoints save +{{< /code >}} + +{{< code shell "Example command" >}} +ETCDCTL_API=3 etcdctl snapshot --endpoints http://localhost:2379 save sensu_etcd_snapshot.db +{{< /code >}} + +{{< /language-toggle >}} + +The command output should be similar to this example: + +{{< code text >}} +root@sensu00:~# etcdctl snapshot --endpoints https://sensu-backend-01:2379 save sensu_etcd_snapshot.db +{"level":"info","ts":"2022-08-18T20:47:28.419Z","caller":"snapshot/v3_snapshot.go:65","msg":"created temporary db file","path":"sensu_etcd_snapshot.db.part"} +{"level":"info","ts":"2022-08-18T20:47:28.452Z","logger":"client","caller":"v3/maintenance.go:211","msg":"opened snapshot stream; downloading"} +{"level":"info","ts":"2022-08-18T20:47:28.452Z","caller":"snapshot/v3_snapshot.go:73","msg":"fetching snapshot","endpoint":"https://sensu-backend-01:2379"} +{"level":"info","ts":"2022-08-18T20:47:28.512Z","logger":"client","caller":"v3/maintenance.go:219","msg":"completed snapshot read; closing"} +{"level":"info","ts":"2022-08-18T20:47:28.648Z","caller":"snapshot/v3_snapshot.go:88","msg":"fetched snapshot","endpoint":"https://sensu-backend-01:2379","size":"2.9 MB","took":"now"} +{"level":"info","ts":"2022-08-18T20:47:28.648Z","caller":"snapshot/v3_snapshot.go:97","msg":"saved","path":"sensu_etcd_snapshot.db"} +Snapshot saved at sensu_etcd_snapshot.db +{{< /code >}} + +### Restore the Sensu configuration for embedded etcd + +If you use embedded etcd for your Sensu instance, follow these steps to restore your Sensu configuration. + +1. Create a new subdirectory: + + {{< code shell >}} +mkdir -p /var/lib/sensu/sensu-backend/new_sensu + +chown -R /var/lib/sensu/sensu-backend/new_sensu +{{< /code >}} + +2. Start a new Sensu backend or cluster: + + {{< language-toggle >}} + +{{< code shell "Single backend startup" >}} +sensu-backend start \ +--etcd-initial-cluster sensu-backend-01=http://sensu-backend-01:2380 \ +--etcd-initial-cluster-token sensu-backend \ +--etcd-initial-advertise-peer-urls http://localhost:2380 \ +--etcd-advertise-client-urls http://localhost:2379 +--state-dir /var/lib/sensu/sensu-backend/new_sensu +{{< /code >}} + +{{< code shell "Clustered backend startup" >}} +sensu-backend start \ +--etcd-initial-cluster sensu-backend-01=http://sensu-backend-01:2380,sensu-backend-02=http://sensu-backend-02:2380,sensu-backend-03=http://sensu-backend-03:2380 \ +--etcd-initial-cluster-token sensu-backend \ +--etcd-initial-advertise-peer-urls http://sensu-backend-01:2380 \ +--etcd-advertise-client-urls http://sensu-backend-01:2379 +--state-dir /var/lib/sensu/sensu-backend/new_sensu + +sensu-backend start \ +--etcd-initial-cluster sensu-backend-01=http://sensu-backend-01:2380,sensu-backend-02=http://sensu-backend-02:2380,sensu-backend-03=http://sensu-backend-03:2380 \ +--etcd-initial-cluster-token sensu-backend \ +--etcd-initial-advertise-peer-urls http://sensu-backend-02:2380 \ +--etcd-advertise-client-urls http://sensu-backend-02:2379 +--state-dir /var/lib/sensu/sensu-backend/new_sensu + +sensu-backend start \ +--etcd-initial-cluster sensu-backend-01=http://sensu-backend-01:2380,sensu-backend-02=http://sensu-backend-02:2380,sensu-backend-03=http://sensu-backend-03:2380 \ +--etcd-initial-cluster-token sensu-backend \ +--etcd-initial-advertise-peer-urls http://sensu-backend-03:2380 \ +--etcd-advertise-client-urls http://sensu-backend-03:2379 +--state-dir /var/lib/sensu/sensu-backend/new_sensu +{{< /code >}} + +{{< /language-toggle >}} + +3. Confirm that the new Sensu backend or cluster is running: + + {{< code shell >}} +systemctl status sensu-backend +{{< /code >}} + + The response should indicate `active (running)`. + +4. Copy the etcd snapshot file to each cluster member so that all members will be restored using the same snapshot. + +5. Restore the Sensu configuration from the etcd snapshot to the running backend or cluster: + + {{< language-toggle >}} + +{{< code shell "Restore a single backend" >}} +ETCDCTL_API=3 etcdctl snapshot restore sensu_etcd_snapshot.db \ +--name sensu-backend-01 \ +--initial-cluster sensu-backend-01=http://sensu-backend-01:2380 \ +--initial-cluster-token sensu-backend \ +--initial-advertise-peer-urls http://sensu-backend-01:2380 \ +--data-dir /var/lib/sensu/sensu-backend/etcd/data \ +--wal-dir /var/lib/sensu/sensu-backend/etcd/wal +{{< /code >}} + +{{< code shell "Restore a clustered backend" >}} +ETCDCTL_API=3 etcdctl snapshot restore sensu_etcd_snapshot.db \ +--name sensu-backend-01 \ +--initial-cluster sensu-backend-01=http://sensu-backend-01:2380,sensu-backend-02=http://sensu-backend-02:2380,sensu-backend-03=http://sensu-backend-03:2380 \ +--initial-cluster-token sensu-backend \ +--initial-advertise-peer-urls http://sensu-backend-01:2380 \ +--data-dir /var/lib/sensu/sensu-backend/etcd/data \ +--wal-dir /var/lib/sensu/sensu-backend/etcd/wal + +ETCDCTL_API=3 etcdctl snapshot restore snapshot.db \ +--name sensu-backend-02 \ +--initial-cluster sensu-backend-01=http://sensu-backend-01:2380,sensu-backend-02=http://sensu-backend-02:2380,sensu-backend-03=http://sensu-backend-03:2380 \ +--initial-cluster-token sensu-backend \ +--initial-advertise-peer-urls http://sensu-backend-02:2380 \ +--data-dir /var/lib/sensu/sensu-backend/etcd/data \ +--wal-dir /var/lib/sensu/sensu-backend/etcd/wal + +ETCDCTL_API=3 etcdctl snapshot restore snapshot.db \ +--name sensu-backend-03 \ +--initial-cluster sensu-backend-01=http://sensu-backend-01:2380,sensu-backend-02=http://sensu-backend-02:2380,sensu-backend-03=http://sensu-backend-03:2380 \ +--initial-cluster-token sensu-backend \ +--initial-advertise-peer-urls http://sensu-backend-03:2380 \ +--data-dir /var/lib/sensu/sensu-backend/etcd/data \ +--wal-dir /var/lib/sensu/sensu-backend/etcd/wal +{{< /code >}} + +{{< /language-toggle >}} + +6. Open the Sensu web UI and confirm that you see the restored Sensu configuration. + +### Restore the Sensu configuration for external etcd + +{{% notice note %}} +**NOTE**: When you create a snapshot, etcdctl copies what etcd is currently using for it's `data-dir` and its `wal-dir`. +For example, if your `data-dir` is `/var/lib/etcd/data` and your `wal dir` is `/var/lib/etcd/wal`, the snapshot you generate will restore the data from the snapshot to those same directories. +This example assumes you are using those directories as a part of your deployment. +If you are using different `data-dir` and `wal-dir` locations, make sure to update the example commands for starting etcd and restoring the snapshot. +{{% /notice %}} + +If you are using an externally deployed etcd instance or cluster, follow these steps to restore your Sensu configuration: + +1. Copy the etcd snapshot file to each cluster member so that all members will be restored using the same snapshot. + +2. Create a new directory on your new etcd cluster: + + {{< code shell >}} +mkdir -p /var/lib/etcd/new_sensu/data + +mkdir -p /var/lib/etcd/new_sensu/wal +{{< /code >}} + +3. Start up etcd using the data and wal directories you created: + + {{< code shell >}} +etcd \ +--listen-client-urls "https://10.0.0.1:2379" \ +--advertise-client-urls "https://10.0.0.1:2379" \ +--listen-peer-urls "https://10.0.0.1:2380" \ +--initial-cluster "backend-1.example.com=https://10.0.0.1:2380,backend-2.example.com=https://10.0.0.2:2380,backend-3.example.com=https://10.0.0.3:2380" \ +--initial-advertise-peer-urls "https://10.0.0.1:2380" \ +--initial-cluster-state "new" \ +--name "backend-1.example.com" \ +--trusted-ca-file=./ca.pem \ +--cert-file=./backend-1.example.com.pem \ +--key-file=./backend-1.example.com-key.pem \ +--client-cert-auth \ +--peer-trusted-ca-file=./ca.pem \ +--peer-cert-file=./backend-1.example.com.pem \ +--peer-key-file=./backend-1.example.com-key.pem \ +--peer-client-cert-auth \ +--auto-compaction-mode revision \ +--auto-compaction-retention 2 +--data-dir /var/lib/etcd/new_sensu/data +--wal-dir /var/lib/etcd/new_sensu/wal + +etcd \ +--listen-client-urls "https://10.0.0.2:2379" \ +--advertise-client-urls "https://10.0.0.2:2379" \ +--listen-peer-urls "https://10.0.0.2:2380" \ +--initial-cluster "backend-1.example.com=https://10.0.0.1:2380,backend-2.example.com=https://10.0.0.2:2380,backend-3.example.com=https://10.0.0.3:2380" \ +--initial-advertise-peer-urls "https://10.0.0.2:2380" \ +--initial-cluster-state "new" \ +--name "backend-1.example.com" \ +--trusted-ca-file=./ca.pem \ +--cert-file=./backend-1.example.com.pem \ +--key-file=./backend-1.example.com-key.pem \ +--client-cert-auth \ +--peer-trusted-ca-file=./ca.pem \ +--peer-cert-file=./backend-1.example.com.pem \ +--peer-key-file=./backend-1.example.com-key.pem \ +--peer-client-cert-auth \ +--auto-compaction-mode revision \ +--auto-compaction-retention 2 +--data-dir /var/lib/etcd/new_sensu/data +--wal-dir /var/lib/etcd/new_sensu/wal + +etcd \ +--listen-client-urls "https://10.0.0.3:2379" \ +--advertise-client-urls "https://10.0.0.3:2379" \ +--listen-peer-urls "https://10.0.0.3:2380" \ +--initial-cluster "backend-1.example.com=https://10.0.0.1:2380,backend-2.example.com=https://10.0.0.2:2380,backend-3.example.com=https://10.0.0.3:2380" \ +--initial-advertise-peer-urls "https://10.0.0.3:2380" \ +--initial-cluster-state "new" \ +--name "backend-1.example.com" \ +--trusted-ca-file=./ca.pem \ +--cert-file=./backend-1.example.com.pem \ +--key-file=./backend-1.example.com-key.pem \ +--client-cert-auth \ +--peer-trusted-ca-file=./ca.pem \ +--peer-cert-file=./backend-1.example.com.pem \ +--peer-key-file=./backend-1.example.com-key.pem \ +--peer-client-cert-auth \ +--auto-compaction-mode revision \ +--auto-compaction-retention 2 +--data-dir /var/lib/etcd/new_sensu/data +--wal-dir /var/lib/etcd/new_sensu/wal +{{< /code >}} + +4. Restore the snapshot: + + {{< code shell >}} +ETCDCTL_API=3 etcdctl snapshot restore sensu_etcd_snapshot.db \ +--name backend-1.example.com \ +--initial-cluster backend-1.example.com=http://10.0.01:2380,backend-2.example.com=http://10.0.0.2:2380,backend-3.example.com=http://10.0.0.3:2380 \ +--initial-cluster-token sensu-backend \ +--initial-advertise-peer-urls http://backend-1.example.com:2380 \ +--data-dir /var/lib/etcd/data \ +--wal-dir /var/lib/etcd/wal + +ETCDCTL_API=3 etcdctl snapshot restore snapshot.db \ +--name backend-2.example.com \ +--initial-cluster backend-1.example.com=http://10.0.01:2380,backend-2.example.com=http://10.0.0.2:2380,backend-3.example.com=http://10.0.0.3:2380 \ +--initial-cluster-token sensu-backend \ +--initial-advertise-peer-urls http://backend-2.example.com:2380 \ +--data-dir /var/lib/etcd/data \ +--wal-dir /var/lib/etcd/wal + +ETCDCTL_API=3 etcdctl snapshot restore snapshot.db \ +--name backend-3.example.com \ +--initial-cluster backend-1.example.com=http://10.0.01:2380,backend-2.example.com=http://10.0.0.2:2380,backend-3.example.com=http://10.0.0.3:2380 \ +--initial-cluster-token sensu-backend \ +--initial-advertise-peer-urls http://backend-3.example.com:2380 \ +--data-dir /var/lib/etcd/data \ +--wal-dir /var/lib/etcd/wal +{{< /code >}} + +5. Restart etcd to point at the restored data and wal directories: + + {{< code shell >}} +etcd \ +--listen-client-urls "https://10.0.0.1:2379" \ +--advertise-client-urls "https://10.0.0.1:2379" \ +--listen-peer-urls "https://10.0.0.1:2380" \ +--initial-cluster "backend-1.example.com=https://10.0.0.1:2380,backend-2.example.com=https://10.0.0.2:2380,backend-3.example.com=https://10.0.0.3:2380" \ +--initial-advertise-peer-urls "https://10.0.0.1:2380" \ +--initial-cluster-state "new" \ +--name "backend-1.example.com" \ +--trusted-ca-file=./ca.pem \ +--cert-file=./backend-1.example.com.pem \ +--key-file=./backend-1.example.com-key.pem \ +--client-cert-auth \ +--peer-trusted-ca-file=./ca.pem \ +--peer-cert-file=./backend-1.example.com.pem \ +--peer-key-file=./backend-1.example.com-key.pem \ +--peer-client-cert-auth \ +--auto-compaction-mode revision \ +--auto-compaction-retention 2 +--data-dir /var/lib/etcd/data +--wal-dir /var/lib/etcd/wal + +etcd \ +--listen-client-urls "https://10.0.0.2:2379" \ +--advertise-client-urls "https://10.0.0.2:2379" \ +--listen-peer-urls "https://10.0.0.2:2380" \ +--initial-cluster "backend-1.example.com=https://10.0.0.1:2380,backend-2.example.com=https://10.0.0.2:2380,backend-3.example.com=https://10.0.0.3:2380" \ +--initial-advertise-peer-urls "https://10.0.0.2:2380" \ +--initial-cluster-state "new" \ +--name "backend-1.example.com" \ +--trusted-ca-file=./ca.pem \ +--cert-file=./backend-1.example.com.pem \ +--key-file=./backend-1.example.com-key.pem \ +--client-cert-auth \ +--peer-trusted-ca-file=./ca.pem \ +--peer-cert-file=./backend-1.example.com.pem \ +--peer-key-file=./backend-1.example.com-key.pem \ +--peer-client-cert-auth \ +--auto-compaction-mode revision \ +--auto-compaction-retention 2 +--data-dir /var/lib/etcd/data +--wal-dir /var/lib/etcd/wal + +etcd \ +--listen-client-urls "https://10.0.0.3:2379" \ +--advertise-client-urls "https://10.0.0.3:2379" \ +--listen-peer-urls "https://10.0.0.3:2380" \ +--initial-cluster "backend-1.example.com=https://10.0.0.1:2380,backend-2.example.com=https://10.0.0.2:2380,backend-3.example.com=https://10.0.0.3:2380" \ +--initial-advertise-peer-urls "https://10.0.0.3:2380" \ +--initial-cluster-state "new" \ +--name "backend-1.example.com" \ +--trusted-ca-file=./ca.pem \ +--cert-file=./backend-1.example.com.pem \ +--key-file=./backend-1.example.com-key.pem \ +--client-cert-auth \ +--peer-trusted-ca-file=./ca.pem \ +--peer-cert-file=./backend-1.example.com.pem \ +--peer-key-file=./backend-1.example.com-key.pem \ +--peer-client-cert-auth \ +--auto-compaction-mode revision \ +--auto-compaction-retention 2 +--data-dir /var/lib/etcd/data +--wal-dir /var/lib/etcd/wal +{{< /code >}} + +6. Confirm that etcd is showing as healthy: + + {{< code shell >}} +curl -s https://10.0.0.1:2379/health +{{< /code >}} + +7. Start up Sensu and point it at the new etcd cluster: + + {{< code shell >}} +sensu-backend start \ +--etcd-trusted-ca-file=./ca.pem \ +--etcd-cert-file=./backend-1.example.com.pem \ +--etcd-key-file=./backend-1.example.com-key.pem \ +--etcd-client-urls='https://10.0.0.1:2379 https://10.0.0.2:2379 https://10.0.0.3:2379' \ +--no-embed-etcd +{{< /code >}} + +8. Open the Sensu web UI and confirm that you see the restored configuration. + +## Best practices for backups + +The best backup plan depends on how much and how often your Sensu configuration changes, as well as your organization's disaster recovery and business continuity goals. + +Business needs will dictate the right plan for your Sensu installation, but following a few best practices helps ensure that backups are available and useful when you need them. + +### Back up on a regular schedule + +Set a regular schedule for creating backups so that you always have a recent backup available. + +A twice-weekly backup is a good starting point but may not be right for your organization. For example, a large Sensu environment that deploys new checks constantly might require more frequent backups, such as every 24 or 48 hours. At the same time, a smaller environment that monitors only system resources might need only one weekly backup. + +### Back up during off-hours + +Creating a backup requires system resources, so we recommend backing up during evening or weekend hours. + +### Omit events from backups + +Even if you make regular backups, events are likely to be outdated by the time you restore them. +The most important part of a backup is capturing the Sensu configuration. + +If you need access to all events, send events to a time-series database (TSDB) for storage instead of including events in routine Sensu backups. + + +[1]: ../../../sensuctl/create-manage-resources/#create-resources +[2]: #best-practices-for-backups +[3]: ../../../sensuctl/back-up-recover/ +[4]: https://etcd.io/docs/latest/install/ +[5]: https://etcd.io/docs/latest/op-guide/recovery/ diff --git a/content/sensu-go/6.12/operations/maintain-sensu/license.md b/content/sensu-go/6.12/operations/maintain-sensu/license.md new file mode 100644 index 0000000000..76b9698e6b --- /dev/null +++ b/content/sensu-go/6.12/operations/maintain-sensu/license.md @@ -0,0 +1,220 @@ +--- +title: "License reference" +linkTitle: "License Reference" +reference_title: "License" +type: "reference" +description: "Activate and manage your Sensu commercial license, entity counts, and entity limits with sensuctl or by logging into your Sensu account." +weight: 40 +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: maintain-sensu +--- + +## Activate your commercial license + +If you haven't already, [install the backend, agent, and sensuctl][2] and [configure sensuctl][3]. + +Log in to your Sensu account at [account.sensu.io][1] and click **Download license** to download your license file. + +{{< figure src="/images/go/commercial/license_download.png" alt="Screenshot of Sensu account license download" link="/images/go/commercial/license_download.png" target="_blank" >}} + +Save your license to a file such as `sensu_license.yml` or `sensu_license.json`. +With the license file downloaded and saved to a file, you can activate your license with sensuctl or the [/license API][4]. + +{{% notice note %}} +**NOTE**: For [clustered configurations](../../deploy-sensu/cluster-sensu), you only need to activate your license for one of the backends within the cluster. +{{% /notice %}} + +To activate your license with sensuctl: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl create --file sensu_license.yml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl create --file sensu_license.json +{{< /code >}} + +{{< /language-toggle >}} + +Use sensuctl to view your license details at any time: + +{{< code shell >}} +sensuctl license info +{{< /code >}} + +For an active license, the response should be similar to this example: + +{{< code text >}} +=== You are currently using 10/100 total entities, 5/50 agent entities, and 5/50 proxy entities +Account Name: Training Team - Sensu +Account ID: 123 +Plan: managed +Version: 1 +Features: all +Issuer: Sensu, Inc. +Issued: 2020-02-15 15:01:44 -0500 -0500 +Valid: true +Valid Until: 2021-02-15 00:00:00 -0800 -0800 +{{< /code >}} + +This response means you do not have an active license: + +{{< code text >}} +Error: not found +{{< /code >}} + +## Entity limit + +Your commercial license may include the entity limit and entity class limits tied to your Sensu licensing package. +[Contact Sensu][8] to upgrade your commercial license. + +Your Sensu license may include two types of entity limits: + +- Entity limit: the maximum number of entities of all classes your license includes. +Both agent and proxy entities count toward the overall entity limit. +- Entity class limits: the maximum number of a specific class of entities (for example, agent or proxy) that your license includes. + +For example, if your license has an entity limit of 10,000 and an agent entity class limit of 3,000, you cannot run more than 10,000 entities (agent and proxy) total. +At the same time, you cannot run more than 3,000 agents. +If you use only 1,500 agent entities, you can have 8,500 proxy entities before you reach the overall entity limit of 10,000. + +If you have permission to create or update licenses, you will see messages in sensuctl and the web UI when you approach your licensed entity limit. +The formula for calculating the threshold for this warning message is `0.03 * entity limit / 1000 + 0.9`. +For example, if your entity limit is 1600, the warning threshold is 0.948. + +You will also see a warning when you exceed your entity or entity class limit. + +### View entity count and entity limit + +Your current entity count and entity limit are included in the `sensuctl license info` response. + +In tabular format, the entity count and limit are included in the response title. +To view license info in tabular format, run: + +{{< code shell >}} +sensuctl license info --format tabular +{{< /code >}} + +The response in tabular format should be similar to this example: + +{{< code text >}} +=== You are currently using 10/100 total entities, 5/50 agent entities, and 5/50 proxy entities +Account Name: Training Team - Sensu +Account ID: 123 +Plan: managed +Version: 1 +Features: all +Issuer: Sensu, Inc. +Issued: 2020-02-15 15:01:44 -0500 -0500 +Valid: true +Valid Until: 2021-02-15 00:00:00 -0800 -0800 +{{< /code >}} + +If you have an unlimited entity count, the `sensuctl license info` response title will still include a current count for each type of entity you are using. +For example: + +{{< code text >}} +=== You are currently using 10/unlimited total entities, 5/unlimited agent entities, and 5/unlimited proxy entities +{{< /code >}} + +To view license details in YAML or JSON, run: + +{{< language-toggle >}} +{{< code shell "YML" >}} +sensuctl license info --format yaml +{{< /code >}} +{{< code shell "JSON" >}} +sensuctl license info --format wrapped-json +{{< /code >}} +{{< /language-toggle >}} + +In YAML and JSON formats, the entity count and limit are included as labels: + +{{< language-toggle >}} + +{{< code text "YML" >}} +--- +type: LicenseFile +api_version: licensing/v2 +metadata: + labels: + sensu.io/entity-count: "10" + sensu.io/entity-limit: "100" +spec: + license: + version: 1 + issue: Sensu, Inc. + accountName: Training Team - Sensu +[...] +{{< /code >}} + +{{< code text "JSON" >}} +{ + "type": "LicenseFile", + "api_version": "licensing/v2", + "metadata": { + "labels": { + "sensu.io/entity-count": "10", + "sensu.io/entity-limit": "100" + } + }, + "spec": { + "license": { + "version": 1, + "issue": "Sensu, Inc.", + "accountName": "Training Team - Sensu" + }, + "...": "..." + } +} +{{< /code >}} + +{{< /language-toggle >}} + +You can also find your current entity count and limit in the response headers for any `/api/core` or `/api/enterprise` [API request][9]. +For example: + +{{< code shell >}} +curl http://127.0.0.1:8080/api/core/v2/namespaces/default/entities -v -H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +The response headers will include your current entity count and limit: + +{{< code text >}} +HTTP/1.1 200 OK +Content-Type: application/json +Sensu-Entity-Count: 10 +Sensu-Entity-Limit: 100 +{{< /code >}} + +## License expiration + +To view your commercial license expiration date, [log in to your Sensu account][1]. + +When your license is within 30 days of expiration, Sensu issues regular warnings in the Sensu [backend logs][6]. +Users with permission to create or update licenses can also view license expiration information in the web UI by pressing `CTRL .` to open the system information modal. + +If your license expires, you will still have access to [commercial features][5], but your entity limit will drop back down to the free limit of 100. + +## Quick links + +- [Log in to your Sensu account][1] +- [Use the license management API][4] +- [Contact Sensu support][8] +- [Contact Sensu sales][7] + + +[1]: https://account.sensu.io/ +[2]: ../../deploy-sensu/install-sensu/ +[3]: ../../../sensuctl/#first-time-setup-and-authentication +[4]: ../../../api/other/license/ +[5]: ../../../commercial/ +[6]: ../troubleshoot/ +[7]: https://sensu.io/contact?subject=contact-sales +[8]: https://account.sensu.io/support +[9]: ../../../api/ diff --git a/content/sensu-go/6.12/operations/maintain-sensu/migrate.md b/content/sensu-go/6.12/operations/maintain-sensu/migrate.md new file mode 100644 index 0000000000..ff70702ed7 --- /dev/null +++ b/content/sensu-go/6.12/operations/maintain-sensu/migrate.md @@ -0,0 +1,640 @@ +--- +title: "Migrate from Sensu Core and Sensu Enterprise to Sensu Go" +linkTitle: "Migrate from Sensu Core and Sensu Enterprise" +description: "Migrate to Sensu Go, which includes important changes to all parts of Sensu and powerful commercial features to make monitoring easier to build and scale." +weight: 20 +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: maintain-sensu +--- + +This guide includes general information for migrating your Sensu instance from Sensu Core and Sensu Enterprise to Sensu Go. +For instructions and tools to help you translate your Sensu configuration from Sensu Core and Enterprise to Sensu Go, review the [Sensu Translator project][18]. + +{{% notice note %}} +**NOTE**: The information in this guide applies to Sensu Enterprise as well as Sensu Core, although we refer to "Sensu Core" for brevity.

    +The step for [translating integrations, contact routing, and LDAP authentication](#step-4-translate-sensu-enterprise-only-features) applies to Sensu Enterprise (but **not** Sensu Core), and it is designated as Sensu Enterprise-only. +{{% /notice %}} + +Sensu Go includes important changes to all parts of Sensu: architecture, installation, resource definitions, the observation data (event) model, check dependencies, filter evaluation, and more. +Sensu Go also includes many powerful [commercial features][27] to make monitoring easier to build, scale, and offer as a self-service tool to your internal customers. + +Sensu Go is available for [Debian- and RHEL-family distributions and Docker][43]. +The Sensu Go agent is also available for Windows. + +{{% notice warning %}} +**WARNING**: To install Sensu Go alongside your current Sensu instance, you must upgrade to at least Sensu Core 1.9.0-2. +If you need to upgrade, [contact Sensu](https://sensu.io/contact). +{{% /notice %}} + +Aside from this migration guide, these resources can help you migrate from Sensu Core or Sensu Enterprise to Sensu Go: + +- [**Sensu Community Slack**][46]: Join hundreds of other Sensu users in our Community Slack, where you can ask questions and benefit from tips others picked up during their own Sensu Go migrations. +- [**Sensu Community Forum**][47]: Drop a question in our dedicated category for migrating to Go. +- [**Sensu Go workshop**][48]: Download the workshop environment and try out some monitoring workflows with Sensu Go. +- [**Sensu Translator**][45]: Use this command-line tool to generate Sensu Go configurations from your Sensu Core config files. + +We also offer [**commercial support** and **professional services** packages][49] to help with your Sensu Go migration. + +## Configuration management with Ansible, Chef, and Puppet + +[Configuration management][44] integrations for Sensu Go are available for Ansible, Chef, and Puppet: + +- [Ansible collection for Sensu Go][77] and [documentation site][78] +- [Chef cookbook for Sensu Go][76] — [contact us][79] for more information +- [Puppet module for Sensu Go][75] + +## Packaging + +Sensu Go is provided as three packages: sensu-go-backend, sensu-go-agent, and sensu-go-cli (sensuctl). +This is a fundamental change in Sensu terminology from Sensu Core: in Sensu Go, the server is now the backend. + +Clients are represented within Sensu Go as abstract [entities][96] that can describe a wider range of system components such as network gear, a web server, or a cloud resource. + +Read [Sensu concepts and terminology][1] to learn more about new terms in Sensu Go. + +## Architecture + +In Sensu Go, an embedded transport and [etcd datastore][2] replace the external RabbitMQ transport and Redis datastore in Sensu Core. + +{{< figure src="/images/go/deployment_architecture/single_backend_standalone_architecture.png" alt="Single Sensu Go backend or standalone architecture" link="/images/go/deployment_architecture/single_backend_standalone_architecture.png" target="_blank" >}} + + +*

    Single Sensu Go backend or standalone architecture

    * + +In Sensu Go, the Sensu backend and agent are configured with YAML files or the `sensu-backend` or `sensu-agent` command line tools rather than JSON files. +Sensu checks and pipeline elements are configured via the API or sensuctl tool in Sensu Go instead of JSON files. + +The [**Sensu backend**][3] is powered by an embedded transport and [etcd][36] datastore and gives you flexible, automated workflows to route metrics and alerts. +Sensu backends require persistent storage for their embedded database, disk space for local dynamic runtime asset caching, and several exposed ports: + +- 2379 (gRPC) Sensu storage client: Required for Sensu backends using an external etcd instance +- 2380 (gRPC) Sensu storage peer: Required for etcd [cluster][37] members to communicate directly with their peers +- 3000 (HTTP/HTTPS) [Sensu web UI][39]: Required for all Sensu backends using a Sensu web UI +- 8080 (HTTP/HTTPS) [Sensu API][40]: Required for all users accessing the Sensu API +- 8081 (WS/WSS) Agent API: Required for all Sensu agents connecting to a Sensu backend + +[**Sensu agents**][4] are lightweight clients that run on the infrastructure components you want to monitor. +Agents automatically register with Sensu as entities and are responsible for creating check and metric events to send to the backend event pipeline. + +The Sensu agent uses: + +- 3030 (TCP/UDP) Sensu agent socket: Required for Sensu agents using the agent socket +- 3031 (HTTP) Sensu [agent API][41]: Required for all users accessing the agent API +- 8125 (UDP) [StatsD listener][42]: Required for all Sensu agents using the StatsD listener + +The agent TCP and UDP sockets are deprecated in favor of the [agent API][41]. + +Agents that use Sensu [dynamic runtime assets][12] require some disk space for a local cache. + +Read the [backend][3], [agent][4], and [sensuctl][5] reference docs for more information. + +## Entities + +Clients are represented within Sensu Go as abstract [entities][96] that can describe a wide range of system components such as network gear, a web server, or a cloud resource. + +Sensu Go includes [agent entities][92] that run a Sensu agent and the familiar [proxy entities][93]. +Sensu Go also includes [service entities][94], which represent business services in the [business service monitoring (BSM)][95] feature. + +Read the [entities reference][6] and the guide to [monitoring external resources][7] for more information about Sensu Go entities. + +## Checks + +In Sensu Go, [checks][97] work with Sensu agents to produce observability events automatically. +The Sensu backend coordinates check execution by comparing the [subscriptions][98] specified in check and entity definitions to determine which entities should receive execution requests for a given check. + +### Subdue + +Sensu Go checks include a `subdues` attribute that allows you to set specific periods of time when Sensu will not execute the check. +Read [Subdues][109] in the checks reference for more information and examples. + +You can also use [cron scheduling][99] in Sensu Go checks to specify when checks **should** be executed. + +### Standalone checks + +Sensu Go does not include standalone checks. +Read [Self-service monitoring checks in Sensu Go][26] to learn more about using role-based access control (RBAC), dynamic runtime assets, and entity subscriptions to achieve similar functionality to Sensu Core's standalone checks in Sensu Go. + +### Check hooks + +[Check hooks][8] are a distinct resource type in Sensu Go, which allows you to create, manage, and reuse hooks independently of check definitions. +You can also execute multiple hooks for any given response code. + +### Default handler + +Sensu Go does not try to run a default handler when executing checks whose definitions do not specify a handler name. +In Sensu Go, you explicitly add the name of a handler in a [pipeline][100] and reference the pipeline in your check definition. + +## Events + +In Sensu Go, all check results are considered events and are processed by [pipelines][100], which include event [filters][9], [mutators][102], and [handlers][103]. + +Use Sensu Go's built-in [is_incident filter][63] to recreate the Sensu Core behavior in which only check results with a non-zero status are considered events. + +## Handlers + +Sensu Go includes pipe and TCP/UDP handlers, but not transport handlers. +To create similar functionality to transport handlers in Sensu Go, create a pipe handler that connects to a message bus and injects event data into a queue. + +Sensu Go also includes streaming handlers, such as the [Sumo Logic metrics handler][104], to provide persistent connections for transmitting Sensu observation data to remote data storage services to help prevent data bottlenecks. + +## Filters + +In Sensu Go, JavaScript expressions replace the Ruby eval logic in Sensu Core, opening up powerful ways to filter events based on occurrences and other event attributes. +As a result, Sensu Go does not include the built-in occurrence-based event filter in Sensu Core. +To replicate the Sensu Core occurrence-based filter's functionality, use Sensu Go's [repeated events filter definition][10]. + +Sensu Go includes three built-in [event filters][9]: [is_incident][63], [not_silenced][61], and [has_metrics][101]. +Sensu Go does not include a built-in check dependencies filter, but you can use the [sensu/sensu-dependencies-filter][23] dynamic runtime asset to replicate the built-in check dependencies filter functionality from Sensu Core. + +Sensu Go event filters do not include the `when` event filter attribute. +Use [Sensu query expressions][108] to build [custom functions][106] that provide granular control of time-based filter expressions. + +### Fatigue check filter + +The [sensu/sensu-go-fatigue-check-filter][11] dynamic runtime asset is a JavaScript implementation of the `occurrences` filter from Sensu Core. +This filter looks for [check and entity annotations][33] in each event it receives and uses the values of those annotations to configure the filter's behavior on a per-event basis. + +The [Sensu Translator version 1.1.0][18] retrieves occurrence and refresh values from a Sensu Core check definition and outputs them as annotations in a Sensu Go check definition, compatible with the fatigue check filter. + +However, the Sensu Translator doesn't automatically add the [sensu/sensu-go-fatigue-check-filter][11] dynamic runtime asset or the filter configuration you need to run it. +To use the sensu/sensu-go-fatigue-check-filter dynamic runtime asset, you must [register it][15], create a correctly configured [event filter definition][19], and [add the event filter][34] to the list of filters on applicable handlers. + +## Dynamic runtime assets + +The `sensu-install` tool in Sensu Core is replaced by [dynamic runtime assets][12] in Sensu Go. +Dynamic runtime assets are shareable, reusable packages that make it easier to deploy Sensu plugins. + +You can still install [Sensu Community plugins][21] in Ruby via `sensu-install` by installing [sensu-plugins-ruby][20]. +Read [Install plugins][51] for more information. + +## Role-based access control (RBAC) + +Role-based access control (RBAC) is a built-in feature of the open-source version of Sensu Go. +RBAC allows you to manage and access users and resources based on namespaces, groups, roles, and bindings. +To set up RBAC in Sensu Go, read the [RBAC reference][13] and [Create a read-only user][14]. + +## Silencing + +Silencing is disabled by default in Sensu Go. +You must explicitly enable silencing by creating silencing resource definitions with sensuctl, the Sensu web UI, or core/v2/silenced API endpoints. +Read the Sensu Go [silencing reference][105] for more information. + +## Token substitution + +The syntax for token substitution changed to [double curly braces][16] in Sensu Go (from triple colons in Sensu Core). + +## Aggregates + +Sensu Go supports check aggregates with the [sensu/sensu-aggregate-check][28] dynamic runtime asset. + +## API + +In addition to the changes to resource definitions, Sensu Go includes new versioned APIs. +Read the [API overview][17] for more information. + +## Step-by-step migration instructions + +### Step 1: Install Sensu Go + +#### 1. Install the Sensu Go backend + +The Sensu backend is available for Debian- and RHEL-family distributions and Docker. +Read the [installation guide][52] to install, configure, and start the Sensu backend according to your [deployment strategy][38]. + +#### 2. Log in to the Sensu web UI + +The [Sensu Go web UI][39] provides a unified view of your observability events with user-friendly tools to reduce alert fatigue and manage your Sensu instance. +After starting the Sensu backend, open the web UI by visiting http://localhost:3000. +You may need to replace `localhost` with the hostname or IP address where the Sensu backend is running. + +To log in, enter your Sensu user credentials or use Sensu's default admin credentials (username: `admin` and password: `P@ssw0rd!`). + +#### 3. Install sensuctl on your workstation + +[Sensuctl][5] is a command line tool for managing resources within Sensu. +It works by calling Sensu’s HTTP API to create, read, update, and delete resources, events, and entities. +Sensuctl is available for Linux, Windows, and macOS. +Read the [installation guide][53] to install and configure sensuctl. + +#### 4. Set up Sensu users + +Use Sensu's built-in [RBAC][13] to manage and access users and resources based on namespaces, groups, roles, and bindings. +To set up RBAC in Sensu Go, read the [RBAC reference][13] and [Create a read-only user][14]. + +In Sensu Go, [namespaces][107] partition resources within a Sensu instance. +Sensu Go entities, checks, handlers, and other [namespaced resources][54] belong to a single namespace. +The Sensu translator places all translated resources into the `default` namespace — we'll use the translater in a moment. + +In addition to built-in RBAC, Sensu Go's [commercial features][27] include support for authentication using Microsoft Active Directory (AD) and standards-compliant Lightweight Directory Access Protocol tools like OpenLDAP. + +#### 5. Install agents + +The Sensu agent is available for Debian- and RHEL-family distributions, Windows, and Docker. +Read the [installation guide][55] to install, configure, and start Sensu agents. + +If you're doing a side-by-side migration, add `api-port` (default: `3031`) and `socket-port` (default: `3030`) to your [agent configuration][56] (`/etc/sensu/agent.yml` or `C:\ProgramData\sensu\config\agent.yml.example`). +This prevents the Sensu Go agent API and socket from conflicting with the Sensu Core client API and socket. + +{{< code yml >}} +api-port: 3031 +socket-port: 3030 +{{< /code >}} + +You can also disable these features in the agent configuration using the `disable-socket` and `disable-api` configuration options. + +Sensu should now be installed and functional. +The next step is to translate your Sensu Core configuration to Sensu Go. + +### Step 2: Translate your configuration + +Use the [Sensu Translator][18] command line tool to transfer your Sensu Core checks, handlers, and mutators to Sensu Go. + +#### 1. Run the translator + +Install dependencies: + +{{< code shell >}} +yum install -q -y rubygems ruby-devel +{{< /code >}} + +Install the Sensu translator: + +{{< code shell >}} +gem install sensu-translator +{{< /code >}} + +Run the Sensu translator to translate all configuration in /etc/sensu/conf.d to Sensu Go and output to /sensu_config_translated: + +{{< code shell >}} +sensu-translator -d /etc/sensu/conf.d -o /sensu_config_translated +{{< /code >}} + +As an option, you can also translate your configuration in sections according to resource type. + +If translation is successful, you should receive a few callouts followed by `DONE!`, similar to this example: + +{{< code text >}} +Sensu 1.x filter translation is not yet supported +Unable to translate Sensu 1.x filter: only_production {:attributes=>{:check=>{:environment=>"production"}}} +DONE! +{{< /code >}} + +Combine your config into a sensuctl-readable format. + +{{% notice note %}} +**NOTE**: for use with `sensuctl create`, do _not_ use a comma between resource objects in Sensu Go resource definitions in JSON format. +{{% /notice %}} + +{{< code shell >}} +find sensu_config_translated/ -name '*.json' -exec cat {} \; > sensu_config_translated_singlefile.json +{{< /code >}} + +Most attributes are ready to use as-is, but you'll need to adjust your Sensu Go configuration manually to migrate some of Sensu's features. + +{{% notice note %}} +**NOTE**: To streamline a comparison of your Sensu Core configuration with your Sensu Go configuration, output your current Sensu Core configuration using the API: `curl -s http://127.0.0.1:4567/settings | jq . > sensu_config_original.json`. +{{% /notice %}} + +#### 2. Translate checks + +Review your Sensu Core check configuration for the following attributes, and make the corresponding updates to your Sensu Go configuration. + +| Core attribute | Manual updates required in Sensu Go config | +| -------------- | ------------- | +`::: foo :::` | Update the syntax for token substitution from triple colons to double curly braces. For example: `{{ foo }}` +`stdin: true` | No updates required. Sensu Go checks accept data on stdin by default. +`handlers: default` | Sensu Go does not have a default handler. Create a handler named `default` to continue using this pattern. +`subdues` | Check subdues are not available in Sensu Go. +`standalone: true` | Standalone checks are not supported in Sensu Go, although you can achieve similar functionality using [role-based access control, dynamic runtime assets, and entity subscriptions][26]. The translator assigns all Core standalone checks to a `standalone` subscription in Sensu Go. Configure one or more Sensu Go agents with the `standalone` subscription to execute Sensu Core standalone checks. +`metrics: true` | Review the [translate metric checks][71] section. +`proxy_requests` | Review the [translate proxy requests][72] section. +`subscribers: roundrobin...` | Remove `roundrobin` from the subscription name, and add the `round_robin` check attribute set to `true`. +`aggregate` | Check aggregates are supported through the [sensu/sensu-aggregate-check][28]. +`hooks` | Review the [translate hooks][73] section. +`dependencies`| Use the [sensu/sensu-dependencies-filter][23] dynamic runtime asset. + +{{% notice protip %}} +**PRO TIP**: When using token substitution in Sensu Go and accessing labels or annotations that include `.`, like `sensu.io.json_attributes`, use the `index` function. +For example, `{{index .annotations "web_url"}}` substitutes the value of the `web_url` annotation; `{{index .annotations "production.ID"}}` substitutes the value of the `production.ID` annotation. +{{% /notice %}} + + + +**Translate metric checks** + +The Sensu Core `type: metric` attribute is not part of the Sensu Go check spec, so you’ll need to adjust it manually. +Sensu Core checks could be configured as `type: metric`, which told Sensu to always handle the check regardless of the check status output. +This allowed Sensu Core to process output metrics via a handler even when the check status was not in an alerting state. + +Sensu Go treats output metrics as first-class objects, so you can process check status as well as output metrics via different event pipelines. +Read the [guide to metric output][57] to update your metric checks with the `output_metric_handlers` and `output_metric_format` attributes and use `output_metric_tags` to enrich extracted metrics output. + + + +**Translate proxy requests and proxy entities** + +Read [Monitor external resources][7] to re-configure `proxy_requests` attributes and update your proxy check configuration. +read the [entities reference][6] to re-create your proxy client configurations as Sensu Go proxy entities. + + + +**Translate hooks** + +Check hooks are now a resource type in Sensu Go, so you can create, manage, and reuse hooks independently of check definitions. +You can also execute multiple hooks for any given response code. +Read the [guide][55] and [hooks reference docs][8] to re-create your Sensu Core hooks as Sensu Go hook resources. + +**Custom attributes** + +Instead of custom check attributes, Sensu Go allows you to add custom labels and annotations to entities, checks, dynamic runtime assets, hooks, filters, mutators, handlers, and silences. +Review the metadata attributes section in the reference documentation for more information about using labels and annotations (for example, [metadata attributes for entities][24]). + +The Sensu Translator stores all check extended attributes in the check metadata annotation named `sensu.io.json_attributes`. +Read the [checks reference][58] for more information about using labels and annotations in check definitions. + +#### 3. Translate event filters + +Ruby eval logic used in Sensu Core filters is replaced with JavaScript expressions in Sensu Go, opening up powerful possibilities to combine filters with [filter dynamic runtime assets][59]. +As a result, you'll need to rewrite your Sensu Core filters in Sensu Go format. + +First, review your Core handlers to identify which filters are being used. +Then, follow the [event filters reference][9] and [guide to using filters][60] to re-write your filters using Sensu Go expressions and [event data][61]. +Check out the [blog post on filters][62] for a deep dive into Sensu Go filter capabilities. + +Sensu Core hourly filter: + +{{< code json >}} +{ + "filters": { + "recurrences": { + "attributes": { + "occurrences": "eval: value == 1 || value % 60 == 0" + } + } + } +} +{{< /code >}} + +Sensu Go hourly filter: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: EventFilter +api_version: core/v2 +metadata: + name: hourly +spec: + action: allow + expressions: + - event.check.occurrences == 1 || event.check.occurrences % (3600 / event.check.interval) == 0 + runtime_assets: null +{{< /code >}} + +{{< code json >}} +{ + "type": "EventFilter", + "api_version": "core/v2", + "metadata": { + "name": "hourly" + }, + "spec": { + "action": "allow", + "expressions": [ + "event.check.occurrences == 1 || event.check.occurrences % (3600 / event.check.interval) == 0" + ], + "runtime_assets": null + } +} +{{< /code >}} + +{{< /language-toggle >}} + +#### 4. Translate handlers + +In Sensu Go, all check results are considered events and are processed by event handlers. +Use the built-in [is_incident filter][63] to recreate the Sensu Core behavior, in which only check results with a non-zero status are considered events. + +{{% notice note %}} +**NOTE**: Silencing is disabled by default in Sensu Go and must be explicitly enabled. +Read the [silencing reference](../../../observability-pipeline/observe-process/silencing/) to create silences in Sensu Go. +{{% /notice %}} + +Review your Sensu Core check configuration for the following attributes and make the corresponding updates to your Sensu Go configuration. + +| Core attribute | Manual updates required in Sensu Go config | +| -------------- | ------------- | +`filters: occurrences` | Replicate the built-in occurrences filter in Sensu Core with the [sensu/sensu-go-fatigue-check-filter][65]. +`type: transport` | Achieve similar functionailty to transport handlers in Sensu Core with a Sensu Go pipe handler that connects to a message bus and injects event data into a queue. +`filters: check_dependencies` | Use the [sensu/sensu-dependencies-filter][23] dynamic runtime asset. +`severities` | Sensu Go does not support severities. +`handle_silenced` | Silencing is disabled by default in Sensu Go and must be explicitly enabled using sensuctl, the web UI, or core/v2/silenced API endpoints. +`handle_flapping` | All check results are considered events in Sensu Go and are processed by [pipelines][100]. + +#### 5. Upload your config to your Sensu Go instance + +After you review your translated configuration, make any necessary updates, and add resource definitions for any filters and entities you want to migrate, you can upload your Sensu Go config using sensuctl. + +{{< code shell >}} +sensuctl create --file /path/to/config.json +{{< /code >}} + +{{% notice protip %}} +**PRO TIP**: `sensuctl create` (and `sensuctl delete`) are powerful tools to help you manage your Sensu configs across namespaces. +Read the [sensuctl reference](../../../sensuctl/) for more information. +{{% /notice %}} + +Access your Sensu Go config using the [Sensu API][17]. + +Set up a local API testing environment by saving your Sensu credentials and token as environment variables. +This command requires curl and jq. + +{{< code shell >}} +export SENSU_USER=admin && SENSU_PASS=P@ssw0rd! +export SENSU_TOKEN=`curl -XGET -u "$SENSU_USER:$SENSU_PASS" -s http://localhost:8080/auth | jq -r ".access_token"` +{{< /code >}} + +Return a list of all configured checks: + +{{< code shell >}} +curl -H "Authorization: Bearer $SENSU_TOKEN" http://127.0.0.1:8080/api/core/v2/namespaces/default/checks +{{< /code >}} + +Return a list of all configured handlers: + +{{< code shell >}} +curl -H "Authorization: Bearer $SENSU_TOKEN" http://127.0.0.1:8080/api/core/v2/namespaces/default/handlers +{{< /code >}} + +You can also access your Sensu Go configuration in JSON or YAML using sensuctl. +For example, `sensuctl check list --format wrapped-json`. +Run `sensuctl help` To view available commands. +For more information about sensuctl's output formats (`json`, `wrapped-json`, and `yaml`), read the [sensuctl reference][22]. + +### Step 3: Translate plugins and register dynamic runtime assets + +#### Sensu plugins + +Within the [Sensu Plugins][21] org, review individual plugin READMEs for compatibility status with Sensu Go. +For handler and mutators plugins, review the [Sensu plugins README][66] to map event data to the [Sensu Go event format][67]. +This allows you to use Sensu plugins for handlers and mutators with Sensu Go without re-writing them. + +To re-install Sensu plugins onto your Sensu Go agent nodes (check plugins) and backend nodes (mutator and handler plugins), read the [guide][51] to installing the `sensu-install` tool for use with Sensu Go. + +#### Sensu Go dynamic runtime assets + +The `sensu-install` tool in Sensu Core is replaced by [dynamic runtime assets][12] in Sensu Go. +Dynamic runtime assets are shareable, reusable packages that make it easier to deploy Sensu plugins. + +Although dynamic runtime assets are not required to run Sensu Go, we recommend [using assets to install plugins][50] where possible. +You can still install [Sensu Community plugins][21] in Ruby via `sensu-install` by installing [sensu-plugins-ruby][20]. +Read [Install plugins][51] for more information. + +Sensu supports dynamic runtime assets for checks, filters, mutators, and handlers. +Discover, download, and share dynamic runtime assets with [Bonsai][68], the Sensu asset hub. + +To create your own dynamic runtime assets, read the [asset reference][12] and [guide to sharing an asset on Bonsai][69]. +To contribute to converting a Sensu plugin to a dynamic runtime asset, read [Contributing Assets for Existing Ruby Sensu Plugins][70] at the Sensu Community Forum on Discourse. + +### Step 4: Translate Sensu Enterprise-only features + +#### Integrations + +Most Sensu Enterprise integrations as available as Sensu Go assets. +Read the [guide to installing plugins with assets][50] to register assets with Sensu and update your Sensu Go handler definitions. + +- [Chef][80] +- [Email][81] +- [Graphite][82] +- [InfluxDB][83] +- [IRC][84] +- [Jira][85] +- [PagerDuty][86] +- [ServiceNow][87] +- [Slack][88] +- [VictorOps][89] + +#### Contact routing + +Contact routing is available in Sensu Go woth the [sensu/sensu-go-has-contact-filter][30] dynamic runtime asset. +Read [Route alerts with event filters][90] to set up contact routing in Sensu Go. + +#### LDAP + +In addition to built-in RBAC, Sensu includes [license-activated][91] support for authentication using Microsoft Active Directory and standards-compliant Lightweight Directory Access Protocol tools like OpenLDAP. + +### Step 5: Sunset your Sensu Core instance + +When you're ready to sunset your Sensu Core instance, stop the Sensu Core services according to the instructions for your [platform][74] — these instructions are listed under **Operating Sensu** on each platform's page. + +After you stop the Sensu Core services, follow package removal instructions for your platform to uninstall the Sensu Core package. + + +[1]: ../../../learn/concepts-terminology/ +[2]: https://etcd.io/docs/latest/ +[3]: ../../../observability-pipeline/observe-schedule/backend/ +[4]: ../../../observability-pipeline/observe-schedule/agent/ +[5]: ../../../sensuctl/ +[6]: ../../../observability-pipeline/observe-entities/entities/ +[7]: ../../../observability-pipeline/observe-entities/monitor-external-resources/ +[8]: ../../../observability-pipeline/observe-schedule/hooks/ +[9]: ../../../observability-pipeline/observe-filter/filters +[10]: ../../../observability-pipeline/observe-filter/filters/#filter-for-repeated-events +[11]: https://bonsai.sensu.io/assets/sensu/sensu-go-fatigue-check-filter/ +[12]: ../../../plugins/assets/ +[13]: ../../control-access/rbac/ +[14]: ../../control-access/create-read-only-user/ +[15]: https://bonsai.sensu.io/assets/sensu/sensu-go-fatigue-check-filter/#asset-registration +[16]: ../../../observability-pipeline/observe-schedule/tokens +[17]: ../../../api/ +[18]: https://github.com/sensu/sensu-translator/ +[19]: https://bonsai.sensu.io/assets/sensu/sensu-go-fatigue-check-filter/#filter-definition +[20]: https://packagecloud.io/sensu/community/ +[21]: https://github.com/sensu-plugins/ +[22]: ../../../sensuctl/#preferred-output-format +[23]: https://bonsai.sensu.io/assets/sensu/sensu-dependencies-filter +[24]: ../../../observability-pipeline/observe-entities/entities#metadata-attributes +[26]: https://sensu.io/blog/self-service-monitoring-checks-in-sensu-go/ +[27]: ../../../commercial/ +[28]: https://bonsai.sensu.io/assets/sensu/sensu-aggregate-check/ +[30]: https://bonsai.sensu.io/assets/sensu/sensu-go-has-contact-filter +[33]: https://bonsai.sensu.io/assets/sensu/sensu-go-fatigue-check-filter/#configuration +[34]: ../../../observability-pipeline/observe-filter/reduce-alert-fatigue/#add-the-event-filter-to-a-pipeline +[36]: https://etcd.io/ +[37]: ../../deploy-sensu/cluster-sensu/ +[38]: ../../deploy-sensu/deployment-architecture/ +[39]: ../../../web-ui/ +[40]: ../../../api/ +[41]: ../../../observability-pipeline/observe-schedule/agent#create-observability-events-using-the-agent-api +[42]: ../../../observability-pipeline/observe-schedule/agent/#create-observability-events-using-the-statsd-listener +[43]: ../../../platforms/ +[44]: ../../deploy-sensu/configuration-management/ +[45]: https://github.com/sensu/sensu-translator +[46]: https://slack.sensu.io/ +[47]: https://discourse.sensu.io/c/sensu-go/migrating-to-go +[48]: https://github.com/sensu/sensu-go-workshop#overview +[49]: https://sensu.io/support/ +[50]: ../../../plugins/use-assets-to-install-plugins/ +[51]: ../../../plugins/install-plugins/ +[52]: ../../deploy-sensu/install-sensu#install-the-sensu-backend +[53]: ../../deploy-sensu/install-sensu#install-sensuctl +[54]: ../../control-access/rbac/#resources +[55]: ../../deploy-sensu/install-sensu#install-sensu-agents +[56]: ../../../observability-pipeline/observe-schedule/agent/#agent-configuration-options +[57]: ../../../observability-pipeline/observe-schedule/collect-metrics-with-checks/ +[58]: ../../../observability-pipeline/observe-schedule/checks#metadata-attributes +[59]: https://bonsai.sensu.io/assets?q=eventfilter +[60]: ../../../observability-pipeline/observe-filter/reduce-alert-fatigue/ +[61]: ../../../observability-pipeline/observe-filter/filters/#build-event-filter-expressions-with-sensu-query-expressions +[62]: https://sensu.io/blog/filters-valves-for-the-sensu-monitoring-event-pipeline +[63]: ../../../observability-pipeline/observe-filter/filters/#built-in-filter-is_incident +[64]: ../../../observability-pipeline/observe-filter/filters/#built-in-filter-not_silenced +[65]: https://bonsai.sensu.io/assets/sensu/sensu-go-fatigue-check-filter +[66]: https://github.com/sensu-plugins/sensu-plugin#sensu-go-enablement +[67]: ../../../observability-pipeline/observe-events/events/#event-format +[68]: https://bonsai.sensu.io +[69]: ../../../plugins/assets/#share-an-asset-on-bonsai +[70]: https://discourse.sensu.io/t/contributing-assets-for-existing-ruby-sensu-plugins/1165 +[71]: #translate-metric-checks +[72]: #translate-proxy-requests-entities +[73]: #translate-hooks +[74]: https://docs.sensu.io/sensu-core/latest/platforms/ +[75]: https://forge.puppet.com/modules/sensu/sensu +[76]: https://supermarket.chef.io/cookbooks/sensu-go +[77]: https://galaxy.ansible.com/sensu/sensu_go +[78]: https://sensu.github.io/sensu-go-ansible/ +[79]: https://monitoringlove.sensu.io/chef +[80]: https://bonsai.sensu.io/assets/sensu-plugins/sensu-plugins-chef +[81]: https://bonsai.sensu.io/assets/sensu/sensu-email-handler +[82]: https://bonsai.sensu.io/assets/sensu/sensu-go-graphite-handler +[83]: https://bonsai.sensu.io/assets/sensu/sensu-influxdb-handler +[84]: https://bonsai.sensu.io/assets/sensu-utils/sensu-irc-handler +[85]: https://bonsai.sensu.io/assets/sensu/sensu-jira-handler +[86]: https://bonsai.sensu.io/assets/sensu/sensu-pagerduty-handler +[87]: https://bonsai.sensu.io/assets/sensu/sensu-servicenow-handler +[88]: https://bonsai.sensu.io/assets/sensu/sensu-slack-handler +[89]: https://bonsai.sensu.io/assets/asachs01/sensu-plugins-victorops +[90]: ../../../observability-pipeline/observe-filter/route-alerts/ +[91]: ../../../commercial +[92]: ../../../observability-pipeline/observe-entities/#agent-entities +[93]: ../../../observability-pipeline/observe-entities/#proxy-entities +[94]: ../../../observability-pipeline/observe-entities/#service-entities +[95]: ../../../observability-pipeline/observe-schedule/business-service-monitoring/ +[96]: ../../../observability-pipeline/observe-entities/ +[97]: ../../../observability-pipeline/observe-schedule/checks/ +[98]: ../../../observability-pipeline/observe-schedule/subscriptions/ +[99]: ../../../observability-pipeline/observe-schedule/checks/#cron-scheduling +[100]: ../../../observability-pipeline/observe-process/pipelines/ +[101]: ../../../observability-pipeline/observe-filter/filters/#built-in-filter-has_metrics +[102]: ../../../observability-pipeline/observe-transform/mutators/ +[103]: ../../../observability-pipeline/observe-process/handlers/ +[104]: ../../../observability-pipeline/observe-process/sumo-logic-metrics-handlers/ +[105]: ../../../observability-pipeline/observe-process/silencing/ +[106]: ../../../observability-pipeline/observe-filter/sensu-query-expressions/#custom-functions-for-weekday-hour-minute-and-second +[107]: ../../control-access/namespaces/ +[108]: ../../../observability-pipeline/observe-filter/sensu-query-expressions/ +[109]: ../../../observability-pipeline/observe-schedule/checks/#subdues diff --git a/content/sensu-go/6.12/operations/maintain-sensu/troubleshoot.md b/content/sensu-go/6.12/operations/maintain-sensu/troubleshoot.md new file mode 100644 index 0000000000..20bfcbca5e --- /dev/null +++ b/content/sensu-go/6.12/operations/maintain-sensu/troubleshoot.md @@ -0,0 +1,940 @@ +--- +title: "Troubleshoot Sensu" +linkTitle: "Troubleshoot" +description: "Here’s how to troubleshoot Sensu, including how to look into errors and use Sensu service logs, which are often the best source of truth for troubleshooting." +weight: 30 +version: "6.12" +product: "Sensu Go" +platformContent: true +platforms: ["Linux", "Windows"] +menu: + sensu-go-6.12: + parent: maintain-sensu +--- + +## Service logging + +Logs produced by Sensu services (sensu-backend and sensu-agent) are often the best place to start when troubleshooting a variety of issues. + +### Log file locations + +{{< platformBlock "Linux" >}} + +#### Linux + +Sensu services print [structured log messages][7] to standard output. +To capture these log messages to disk or another logging facility, Sensu services use capabilities provided by the underlying operating system's service management. +For example, logs are sent to the journald when systemd is the service manager, whereas log messages are redirected to `/var/log/sensu` when running under sysv init schemes. +If you are running systemd as your service manager and would rather have logs written to `/var/log/sensu/`, read [forwarding logs from journald to syslog][11]. + +For journald targets, use these commands to follow the logs. +Replace the `` variable with the name of the desired service (for example, `backend` or `agent`). + +{{< language-toggle >}} + +{{< code shell "RHEL/family >= 7" >}} +journalctl --follow --unit sensu- +{{< /code >}} + +{{< code shell "Ubuntu >= 15.04" >}} +journalctl --follow --unit sensu- +{{< /code >}} + +{{< code shell "Debian >= 8" >}} +journalctl --follow --unit sensu- +{{< /code >}} + +{{< /language-toggle >}} + +For log file targets, use these commands to follow the logs. +Replace the `` variable with the name of the desired service (for example, `backend` or `agent`). + +{{< language-toggle >}} + +{{< code shell "RHEL/family <= 6" >}} +tail --follow /var/log/sensu/sensu- +{{< /code >}} + +{{< code shell "Ubuntu <= 14.10" >}} +tail --follow /var/log/sensu/sensu- +{{< /code >}} + +{{< code shell "Debian <= 7" >}} +tail --follow /var/log/sensu/sensu- +{{< /code >}} + +{{< /language-toggle >}} + +{{% notice note %}} +**NOTE**: Platform versions are listed for reference only and do not supersede the documented [supported platforms](../../../platforms). +{{% /notice %}} + +##### Narrow your search to a specific timeframe + +Use the `journald` keyword `since` to refine the basic `journalctl` commands and narrow your search by timeframe. + +Retrieve all the logs for sensu-backend since yesterday: + +{{< code shell >}} +journalctl -u sensu-backend --since yesterday | tee sensu-backend-$(date +%Y-%m-%d).log +{{< /code >}} + +Retrieve all the logs for sensu-agent since a specific time: + +{{< code shell >}} +journalctl -u sensu-agent --since 09:00 --until "1 hour ago" | tee sensu-agent-$(date +%Y-%m-%d).log +{{< /code >}} + +Retrieve all the logs for sensu-backend for a specific date range: + +{{< code shell >}} +journalctl -u sensu-backend --since "2015-01-10" --until "2015-01-11 03:00" | tee sensu-backend-$(date +%Y-%m-%d).log +{{< /code >}} + +{{< platformBlockClose >}} + +##### Logging edge cases + +If a Sensu service experiences a panic crash, the service may seem to start and stop without producing any output in journalctl. +This is due to a [bug in systemd][12]. + +In these cases, try using the `_COMM` variable instead of the `-u` flag to access additional log entries: + +{{< code shell >}} +journalctl _COMM=sensu-backend.service --since yesterday +{{< /code >}} + +{{< platformBlock "Windows" >}} + +#### Windows + +The Sensu agent stores service logs to the location specified by the `log-file` configuration option (default `%ALLUSERSPROFILE%\sensu\log\sensu-agent.log`, `C:\ProgramData\sensu\log\sensu-agent.log` on standard Windows installations). +For more information about managing the Sensu agent for Windows, read the [agent reference][1]. +You can also view agent events using the Windows Event Viewer, under Windows Logs, as events with source SensuAgent. + +If you're running a [binary-only distribution of the Sensu agent for Windows][2], you can follow the service log printed to standard output using this command: + +{{< code text >}} +Get-Content - Path "C:\scripts\test.txt" -Wait +{{< /code >}} + +{{< platformBlockClose >}} + +### Log levels + +Each log message is associated with a log level that indicates the relative severity of the event being logged: + +| Log level | Description | +|--------------------|--------------------------------------------------------------------------| +| panic | Severe errors that cause the service to shut down in an unexpected state | +| fatal | Fatal errors that cause the service to shut down (status 0) | +| error | Non-fatal service error messages | +| warn | Warning messages that indicate potential issues | +| info | Information messages that represent service actions | +| debug | Detailed service operation messages to help troubleshoot issues | +| trace | Confirmation messages about whether a rule authorized a request | + +You can configure these log levels by specifying the desired log level as the value of `log-level` in the service configuration file (`agent.yml` or `backend.yml`) or as an argument to the `--log-level` command line flag: + +{{< code shell >}} +sensu-agent start --log-level debug +{{< /code >}} + +You must restart the service after you change log levels via configuration files or command line arguments. +For help with restarting a service, read the [agent reference][5] or [backend reference][9]. + +#### Increment log level verbosity + +To increment the log level verbosity at runtime for the backend, run: + +{{< code shell >}} +kill -s SIGUSR1 $(pidof sensu-backend) +{{< /code >}} + +To increment the log level verbosity at runtime for the agent, run: + +{{< code shell >}} +kill -s SIGUSR1 $(pidof sensu-agent) +{{< /code >}} + +When you increment the log at the trace level (the most verbose log level), the log will wrap around to the error level. + +## Sensu backend startup errors + +The following errors are expected when starting up a Sensu backend with the default configuration: + +{{< code text >}} +{"component":"etcd","level":"warning","msg":"simple token is not cryptographically signed","pkg":"auth","time":"2019-11-04T10:26:31-05:00"} +{"component":"etcd","level":"warning","msg":"set the initial cluster version to 3.5","pkg":"etcdserver/membership","time":"2019-11-04T10:26:31-05:00"} +{"component":"etcd","level":"warning","msg":"serving insecure client requests on 127.0.0.1:2379, this is strongly discouraged!","pkg":"embed","time":"2019-11-04T10:26:33-05:00"} +{{< /code >}} + +The `serving insecure client requests` warning is an expected warning from the embedded etcd database. +[TLS configuration][3] is recommended but not required. +For more information, read the [etcd security documentation][4]. + +## CommonName deprecation in Go 1.15 + +As of [Go 1.15][27], certificates must include their CommonName (CN) as a Subject Alternative Name (SAN) field. + +The following logged error indicates that a certificate used to secure Sensu does not include the CN as a SAN field: + +{{< code text >}} +{"component":"agent","error":"x509: certificate relies on legacy Common Name field, use SANs or temporarily enable Common Name matching with GODEBUG=x509ignoreCN=0","level":"error","msg":"reconnection attempt failed","time":"2021-06-29T11:07:51+02:00"} +{{< /code >}} + +If you see this connection error, follow [Generate certificates][28] to make sure your certificates' SAN fields include their CNs. + +## Permission issues + +The Sensu user and group must own files and folders within `/var/cache/sensu/` and `/var/lib/sensu/`. +You will receive a logged error like those listed here if there is a permission issue with either the sensu-backend or the sensu-agent: + +{{< code text >}} +{"component":"agent","error":"open /var/cache/sensu/sensu-agent/assets.db: permission denied","level":"fatal","msg":"error executing sensu-agent","time":"2019-02-21T22:01:04Z"} +{"component":"backend","level":"fatal","msg":"error starting etcd: mkdir /var/lib/sensu: permission denied","time":"2019-03-05T20:24:01Z"} +{{< /code >}} + +Use a recursive `chown` to resolve permission issues with the sensu-backend: + +{{< code shell >}} +sudo chown -R sensu:sensu /var/cache/sensu/sensu-backend +{{< /code >}} + +or the sensu-agent: + +{{< code shell >}} +sudo chown -R sensu:sensu /var/cache/sensu/sensu-agent +{{< /code >}} + +## Handlers and event filters + +Whether implementing new workflows or modifying existing workflows, you may need to troubleshoot various stages of the event pipeline. + +### Create an agent API test event + +In many cases, generating events using the [agent API][6] will save you time and effort over modifying existing check configurations. + +Here's an example that uses cURL with the API of a local sensu-agent process to generate test-event check results: + +{{< code shell >}} +curl -X POST \ +-H 'Content-Type: application/json' \ +-d '{ + "check": { + "metadata": { + "name": "test-event" + }, + "status": 2, + "output": "this is a test event targeting the email_ops handler", + "handlers": [ "email_ops" ] + } +}' \ +http://127.0.0.1:3031/events +{{< /code >}} + +### Use a debug handler + +It may also be helpful to review the complete event object being passed to your workflows. +We recommend using a debug handler like this one to write an event to disk as JSON data: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Handler +api_version: core/v2 +metadata: + name: debug +spec: + type: pipe + command: cat > /var/log/sensu/debug-event.json + timeout: 2 +{{< /code >}} + +{{< code json >}} +{ + "type": "Handler", + "api_version": "core/v2", + "metadata": { + "name": "debug" + }, + "spec": { + "type": "pipe", + "command": "cat > /var/log/sensu/debug-event.json", + "timeout": 2 + } +} +{{< /code >}} + +{{< /language-toggle >}} + +With this handler definition installed in your Sensu backend, you can add the `debug` to the list of handlers in your test event: + +{{< code shell >}} +curl -X POST \ +-H 'Content-Type: application/json' \ +-d '{ + "check": { + "metadata": { + "name": "test-event" + }, + "status": 2, + "output": "this is a test event targeting the email_ops handler", + "handlers": [ "email_ops", "debug" ] + } +}' \ +http://127.0.0.1:3031/events +{{< /code >}} + +The observability event data should be written to `/var/log/sensu/debug-event.json` for inspection. +The contents of this file will be overwritten by every event sent to the `debug` handler. + +{{% notice note %}} +**NOTE**: When multiple Sensu backends are configured in a cluster, event processing is distributed across all members. +You may need to check the filesystem of each Sensu backend to locate the debug output for your test event. +{{% /notice %}} + +### Manually execute a handler + +If you are not receiving events via a handler even though a check is generating events as expected, follow these steps to manually execute the handler and confirm whether the handler is working properly. + +1. List all events: +{{< code shell >}} +sensuctl event list +{{< /code >}} + + Choose an event from the list to use for troubleshooting and note the event's check and entity names. + +2. Navigate to the `/var/cache/sensu/sensu-backend/` directory: +{{< code shell >}} +cd /var/cache/sensu/sensu-backend/ +{{< /code >}} + +3. Run `ls` to list the contents of the `/var/cache/sensu/sensu-backend/` directory. +In the list, identify the handler's dynamic runtime asset SHA. + + {{% notice note %}} +**NOTE**: If the list includes more than one SHA, run `sensuctl asset list`. +In the response, the Hash column contains the first seven characters for each asset build's SHA. +Note the hash for your build of the handler asset and compare it with the SHAs listed in the `/var/cache/sensu/sensu-backend/` directory to find the correct handler asset SHA. +{{% /notice %}} + +4. Navigate to the `bin` directory for the handler asset SHA. +Before you run the command below, replace `` with the SHA you identified in the previous step. +{{< code shell >}} +cd /bin +{{< /code >}} + +5. Run the command to manually execute the handler. +Before you run the command below, replace the following text: + - ``: Replace with the entity name for the event you are using to troubleshoot. + - ``: Replace with the check name for the event you are using to troubleshoot. + - ``: Replace with the `command` value for the handler you are troubleshooting. + + {{< code shell >}} +sensuctl event info --format json | ./ +{{< /code >}} + +If your handler is working properly, you will receive an alert for the event via the handler. +The response for your manual execution command will also include a message to confirm notification was sent. +In this case, your Sensu pipeline is not causing the problem with missing events. + +If you do not receive an alert for the event, the handler is not working properly. +In this case, the manual execution response will include the message `Error executing :` followed by a description of the specific error to help you correct the problem. + +## Dynamic runtime assets + +Use the information in this section to troubleshoot error messages related to dynamic runtime assets. + +### Incorrect asset filter + +Dynamic runtime asset filters allow you to scope an asset to a particular operating system or architecture. +For an example, read the [asset reference][10]. +An improperly applied asset filter can prevent the asset from being downloaded by the desired entity and result in error messages both on the agent and the backend illustrating that the command was not found: + +**Agent log entry** + +{{< code json >}} +{ + "asset": "check-disk-space", + "component": "asset-manager", + "entity": "sensu-centos", + "filters": [ + "true == false" + ], + "level": "debug", + "msg": "entity not filtered, not installing asset", + "time": "2020-09-12T18:28:05Z" +} +{{< /code >}} + +**Backend event** + +{{< language-toggle >}} + +{{< code yml >}} +--- +timestamp: 1568148292 +check: + command: check-disk-space + handlers: [] + high_flap_threshold: 0 + interval: 10 + low_flap_threshold: 0 + publish: true + runtime_assets: + - sensu-disk-checks + subscriptions: + - caching_servers + proxy_entity_name: '' + check_hooks: + stdin: false + subdue: + ttl: 0 + timeout: 0 + round_robin: false + duration: 0.001795508 + executed: 1568148292 + history: + - status: 127 + executed: 1568148092 + issued: 1568148292 + output: 'sh: check-disk-space: command not found' + state: failing + status: 127 + total_state_change: 0 + last_ok: 0 + occurrences: 645 + occurrences_watermark: 645 + output_metric_format: '' + output_metric_handlers: + output_metric_tags: + env_vars: + metadata: + name: failing-disk-check + namespace: default +metadata: + namespace: default +{{< /code >}} + +{{< code json >}} +{ + "timestamp": 1568148292, + "check": { + "command": "check-disk-space", + "handlers": [], + "high_flap_threshold": 0, + "interval": 10, + "low_flap_threshold": 0, + "publish": true, + "runtime_assets": [ + "sensu-disk-checks" + ], + "subscriptions": [ + "caching_servers" + ], + "proxy_entity_name": "", + "check_hooks": null, + "stdin": false, + "subdue": null, + "ttl": 0, + "timeout": 0, + "round_robin": false, + "duration": 0.001795508, + "executed": 1568148292, + "history": [ + { + "status": 127, + "executed": 1568148092 + } + ], + "issued": 1568148292, + "output": "sh: check-disk-space: command not found\n", + "state": "failing", + "status": 127, + "total_state_change": 0, + "last_ok": 0, + "occurrences": 645, + "occurrences_watermark": 645, + "output_metric_format": "", + "output_metric_handlers": null, + "output_metric_tags": null, + "env_vars": null, + "metadata": { + "name": "failing-disk-check", + "namespace": "default" + } + }, + "metadata": { + "namespace": "default" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +If you receive a message like this, review your asset definition — it means that the entity wasn't able to download the required asset due to asset filter restrictions. +To review the filters for an asset, use the sensuctl `asset info` command with a `--format` flag: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl asset info sensu-disk-checks --format yaml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl asset info sensu-disk-checks --format wrapped-json +{{< /code >}} + +{{< /language-toggle >}} + +#### Conflating operating systems with families + +A common asset filter issue is conflating operating systems with the family they're a part of. +For example, although Ubuntu is part of the Debian family of Linux distributions, Ubuntu is not the same as Debian. +A practical example might be: + +{{< language-toggle >}} + +{{< code yml >}} +filters: +- entity.system.platform == 'debian' +- entity.system.arch == 'amd64' +{{< /code >}} + +{{< code json >}} +{ + "filters": [ + "entity.system.platform == 'debian'", + "entity.system.arch == 'amd64'" + ] +} +{{< /code >}} + +{{< /language-toggle >}} + +This would not allow an Ubuntu system to run the asset. + +Instead, the asset filter should look like this: + +{{< language-toggle >}} + +{{< code yml >}} +filters: +- entity.system.platform_family == 'debian' +- entity.system.arch == 'amd64' +{{< /code >}} + +{{< code json >}} +{ + "filters": [ + "entity.system.platform_family == 'debian'", + "entity.system.arch == 'amd64'" + ] +} +{{< /code >}} +{{< /language-toggle >}} + +or + +{{< language-toggle >}} + +{{< code yml >}} +filters: +- entity.system.platform == 'ubuntu' +- entity.system.arch == 'amd64' +{{< /code >}} + +{{< code json >}} +{ + "filters": [ + "entity.system.platform == 'ubuntu'", + "entity.system.arch == 'amd64'" + ] +} +{{< /code >}} + +{{< /language-toggle >}} + +This would allow the asset to be downloaded onto the target entity. + +#### Running the agent on an unsupported Linux platform + +If you run the Sensu agent on an unsupported Linux platform, the agent might fail to correctly identify your version of Linux and could download the wrong version of an asset. + +This issue affects Linux distributions that do not include the `lsb_release` package in their default installations. +In this case, `gopsutil` may try to open `/etc/lsb_release` or try to run `/usr/bin/lsb_release` to find system information, including Linux version. +Since the `lsb_release` package is not installed, the agent will not be able to discover the Linux version as expected. + +To resolve this problem, install the [`lsb_release` package][8] for your Linux distribution. + +### Checksum mismatch + +When a downloaded dynamic runtime asset checksum does not match the checksum specified in the asset definition, the agent logs a message similar to this example: + +{{< code json >}} +{ + "asset": "check-disk-space", + "component": "asset-manager", + "entity": "sensu-centos", + "filters": [ + "true == false" + ], + "level": "debug", + "msg": "error getting assets for check: could not validate downloaded asset $ASSET_NAME (X.X MB): sha512 of downloaded asset (6b73p32XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX) does not match specified sha512 in asset definition (e6b7c8eXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX)", + "time": "2019-09-12T18:28:05Z" +} +{{< /code >}} + +To correct this issue, first confirm that the URL in the asset definition is valid. +Manually download the asset with a cURL or wget command and make sure that the downloaded file is a valid `tar.gz` file with the contents you expect. + +If the downloaded `tar.gz` file contents are correct, use the [`sha512sum` command][21] to calculate the asset checksum and manually confirm that the checksum in the downloaded asset definition is correct. + +If the checksum in the downloaded asset definition is correct, confirm that there is enough space available in `/tmp` to download the asset. +On Linux systems, the Sensu agent downloads assets into `/tmp`. +The log error message specifies the size of the asset artifact in parentheses after the asset name. +If space in `/tmp` is insufficient, asset downloads will be truncated and the checksum will not be validated. + +### Certificate error when fetching assets + +When Sensu cannot fetch the assets referenced in a resource definition, the agent logs a message similar to this example: + +{{< code text >}} +error getting assets for check: error fetching asset: Get "https://assets.bonsai.sensu.io/2940de675113d07710c0f896efa8b43b7c301c5c/sensu-plugins-process-checks_4.0.0_centos_linux_amd64.tar.gz": x509: certificate signed by unknown authority +{{< /code >}} + +To correct this issue, confirm that you can download the asset from one of the agent hosts using the link quoted in the error message. +If the download does not work, the problem may be due to a proxy between the agent and the internet or the proxy settings. + +If there are no proxies or no proxy settings of concern, you may need to update the certificate store on your agents. +The https://assets.bonsai.sensu.io SSL certificate uses the AWS Private Certificate Authority (CA), which your agents' operating systems should be configured to trust. + +If you are using PowerShell, you may see this error if PowerShell is configured to use TLS 1.0 — https://assets.bonsai.sensu.io requires TLS 1.2. + +To check which TLS version PowerShell is using, run: + +{{< code powershell >}} +[Net.ServicePointManager]::SecurityProtocol +{{< /code >}} + +If the response does not include `Tls12`, run the following command to require it: + +{{< code powershell >}} +[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 +{{< /code >}} + +## Etcd clusters + +Some issues require you to investigate the state of the etcd cluster or data stored within etcd. +In these cases, we suggest using the [etcdctl tool][29] to query and manage the etcd database. + +Sensu's supported packages do not include the etcdctl executable, so you must get it from a compatible etcd release. + +### Configure etcdctl environment variables + +To use etcdctl to investigate etcd cluster and data storage issues, first run these commands to configure etcdctl environment variables: + +{{< code shell >}} +export ETCDCTL_API=3 +export ETCDCTL_CACERT=/etc/sensu/ca.pem +export ETCDCTL_ENDPOINTS="https://backend01:2379,https://backend02:2379,https://backend03:2379" +{{< /code >}} + +If your etcd uses client certificate authentication, run these commands too: + +{{< code shell >}} +export ETCDCTL_CERT=/etc/sensu/cert.pem +export ETCDCTL_KEY=/etc/sensu/key.pem +{{< /code >}} + +### View cluster status and alarms + +Use the commands listed here to retrieve etcd cluster status and list and clear alarms. + +To retrieve etcd cluster status: + +{{< code shell >}} +etcdctl endpoint status +{{< /code >}} + +To retrieve a list of etcd alarms: + +{{< code shell >}} +etcdctl alarm list +{{< /code >}} + +To clear etcd alarms: + +{{< code shell >}} +etcdctl alarm disarm +{{< /code >}} + +### Restore a cluster with an oversized database + +The default Sensu backend configuration sets the maximum etcd database size to 4 GB. +If you suspect your etcd database exceeds 4 GB, run this command to confirm cluster size: + +{{< code shell >}} +etcdctl endpoint status +{{< /code >}} + +The response will list the current cluster status and database size: + +{{< code text >}} +https://backend01:2379, 88db026f7feb72b4, 3.5.0, 4.1GB, false, 144, 18619245 +https://backend02:2379, e98ad7a888d16bd6, 3.5.0, 4.1GB, true, 144, 18619245 +https://backend03:2379, bc4e39432cbb36d, 3.5.0, 4.1GB, false, 144, 18619245 +{{< /code >}} + +To restore an etcd cluster with a database size that exceeds 4 GB: + +1. Get the current revision number: +{{< code shell >}} +etcdctl endpoint status --write-out="json" | egrep -o '"revision":[0-9]*' | egrep -o '[0-9].*' +{{< /code >}} + +2. Compact to revision and substitute the current revision for `$rev`: +{{< code shell >}} +etcdctl compact $rev +{{< /code >}} + +3. Defragment to free up space: +{{< code shell >}} +etcdctl defrag +{{< /code >}} + +4. Confirm that the cluster is restored: +{{< code shell >}} +etcdctl endpoint status +{{< /code >}} + + The response should list the current cluster status and database size: +{{< code text >}} +https://backend01:2379, 88db026f7feb72b4, 3.5.0, 1.0 MB, false, 144, 18619245 +https://backend02:2379, e98ad7a888d16bd6, 3.5.0, 1.0 MB, true, 144, 18619245 +https://backend03:2379, bc4e39432cbb36d, 3.5.0, 1.0 MB, false, 144, 18619245 +{{< /code >}} + +### Remove and redeploy a cluster + +{{% notice protip %}} +**PRO TIP**: If you are using embedded or external etcd, use [etcd snapshots](https://etcd.io/docs/latest/op-guide/recovery/) to keep a backup so that you can restore your Sensu resources if you have to redeploy your cluster. +For extra reassurance, take regular etcd snapshots and make regular backups with [sensuctl dump](../../../sensuctl/back-up-recover/) in addition to etcd's running snapshots.

    +If you wait until cluster nodes are failing, it may not be possible to make a backup. +For example, in a three-node cluster, if one node fails, you will still be able to make a backup. +If two nodes fail, the whole cluster will be down and you will not be able to create a snapshot or run sensuctl dump.

    +Read [Restore your Sensu configuration for disaster recovery](../disaster-recovery/) for backup instructions and best practices. +{{% /notice %}} + +You may need to completely remove a cluster and redeploy it in cases such as: + +- Failure to reach consensus after losing more than `(N-1)/2` cluster members +- Etcd configuration issues +- Etcd corruption, perhaps from disk filling +- Unrecoverable hardware failure + +To remove and redeploy a cluster: + +1. Open a terminal window for each cluster member. + +2. Stop each cluster member backend: +{{< code shell >}} +systemctl stop sensu-backend +{{< /code >}} + +3. Confirm that each backend stopped: +{{< code shell >}} +systemctl status sensu-backend +{{< /code >}} + + For each backend, the response should begin with the following lines: + {{< code text >}} +● sensu-backend.service - The Sensu Backend service. +Loaded: loaded (/usr/lib/systemd/system/sensu-backend.service; disabled; vendor preset: disabled) +Active: inactive (dead) +{{< /code >}} + +4. Delete the etcd directories for each cluster member: +{{< code shell >}} +rm -rf /var/lib/sensu/sensu-backend/etcd/ +{{< /code >}} + +5. Follow the [Sensu backend configuration][23] instructions to reconfigure a new cluster. + +6. [Initialize][25] a backend to specify admin credentials: +{{< code shell >}} +sensu-backend init --interactive +{{< /code >}} + + When you receive prompts for your username and password, replace `` and `` with the administrator username and password you want to use for the cluster members: +{{< code text >}} +Admin Username: +Admin Password: +{{< /code >}} + +7. Restore your cluster from a snapshot or backup: + - Follow the [etcd restore process][26] (for external etcd). + - Use [sensuctl create][24] (for external or embedded etcd). + +## Datastore performance + +In a default deployment, Sensu uses [etcd datastore][17] for both configuration and state. +As the number of checks and entities in your Sensu installation increases, so does the volume of read and write requests to etcd database. + +One trade-off in etcd's design is its sensitivity to disk and CPU latency. +When certain latency tolerances are regularly exceeded, failures will cascade. +Sensu will attempt to recover from these conditions when it can, but this may not be successful. + +To maximize Sensu Go performance, we recommend that you: + * Follow our [recommended backend hardware configuration][19]. + * Implement [documented etcd system tuning practices][14]. + * [Benchmark your etcd storage volume][15] to establish baseline IOPS for your system. + * [Scale event storage using PostgreSQL][16] with [round robin scheduling enabled][20] to reduce the overall volume of etcd transactions. + + As your Sensu deployments grow, preventing issues associated with poor datastore performance relies on ongoing collection and review of [Sensu time-series performance metrics][18]. + +### Symptoms of poor performance + +At the Sensu backend's default "warn" log level, you may receive messages like these from your backend: + +{{< code text >}} +{"component":"etcd","level":"warning","msg":"read-only range request \"key:\\\"/sensu.io/handlers/default/keepalive\\\" limit:1 \" with result \"range_response_count:0 size:6\" took too long (169.767546ms) to execute","pkg":"etcdserver","time":"..."} +{{< /code >}} + +The above message indicates that a database query ("read-only range request") exceeded a 100-millisecond threshold hard-coded into etcd. +Messages like these are helpful because they can alert you to a trend, but these occasional warnings don't necessarily indicate a problem with Sensu. +For example, you may receive this message if you provision attached storage but do not mount it to the etcd data directory. + +However, a trend of increasingly long-running database transactions will eventually lead to decreased reliability. +You may experience symptoms of these conditions as inconsistent check execution behavior or configuration updates that are not applied as expected. + +As the [etcd tuning documentation][14] states: + +> An etcd cluster is very sensitive to disk latencies. Since etcd must persist proposals to its log, disk activity from other processes may cause long fsync latencies. [...] etcd may miss heartbeats, causing request timeouts and temporary leader loss. + +When Sensu's etcd component doesn't recieve sufficient CPU cycles or its file system can't sustain a sufficient number of IOPS, transactions will begin to timeout, leading to cascading failures. + +A message like this indicates that syncing the etcd database to disk exceeded another threshold: + +{{< code text >}} +{"component":"etcd","level":"warning","msg":"sync duration of 1.031759056s, expected less than 1s","pkg":"wal","time":"..."} +{{< /code >}} + +These subsequent "retrying of unary invoker failed" messages indicate failing requests to etcd: + +{{< code text >}} +{"level":"warn","ts":"...","caller":"clientv3/retry_interceptor.go:62","msg":"retrying of unary invoker failed","target":"endpoint://client-6f6bfc7e-cf31-4498-a564-78d6b7b3a44e/localhost:2379","attempt":0,"error":"rpc error: code = Canceled desc = context canceled"} +{{< /code >}} + +On busy systems you may also receive output like "message repeated 5 times" indicating that failing requests were retried multiple times. + +In many cases, the backend service detects and attempts to recover from errors like these, so you may receive a message like this: + +{{< code text >}} +{"component":"backend","error":"error from keepalived: internal error: etcdserver: request timed out","level":"error","msg":"backend stopped working and is restarting","time":"..."} +{{< /code >}} + +This may result in a crash loop that is difficult to recover from. +You may observe that the Sensu backend process continues running but is not listening for connections on the agent WebSocket, API, or web UI ports. +The backend will stop listening on those ports when the etcd database is unavailable. + +## Check execution errors + +The Sensu backend sends check requests to all matching subscriptions. +If an entity and a check have multiple matching subscriptions, the entity will receive a separate check request for each matching subscription. +The entity could receive both check requests almost simultaneously. + +As a result, you may see one or more of the following error messages: + +{{< code text >}} +{"component":"agent","error":"check execution still in progress: ","level":"error","msg":"error handling message","time":"..."} + +{"component":"agent","error":"check request is older than a previously received check request","level":"error","msg":"error handling message","time":"..."} + +{"component":"agent","warning":"check request has already been received - agent and check may have multiple matching subscriptions","level":"warn","msg":"error handling message","time":"..."} +{{< /code >}} + +Entities may execute the duplicate check requests quickly enough to prevent these errors. +In these cases, check `history` and features that rely on it, like flap detection, may behave in unexpected ways. + +If you see any of the check execution errors listed above, review the check subscriptions against your entities for multiple matching subscriptions. +To prevent the problem, make sure that your checks and entities share only a single [subscription][31]. + +## Web UI errors + +If the web UI experiences an error, you may see the following message in the web UI: + +{{< figure src="/images/go/troubleshoot/web_ui_error.png" alt="Web UI error message with options for clearing state and reloading" link="/images/go/troubleshoot/web_ui_error.png" target="_blank" >}} + +The error message indicates something unexpected happened, such as the server failing to return the correct response. +Clicking **RELOAD** can resolve most common problems. + +More rarely, the error can result from issues like a corrupt cache or a bad persistent state. +In these cases, clicking **CLEAR STATE & RELOAD** usually resolves the issue. + +### Investigate a web UI error + +To get more information about a web UI error, open your web browser's developer console to view the error messages your browser logged. + +Use these keyboard shortcuts to open the developer console on different operating systems: + +Operating system | Keyboard shortcut +------- | ------------ +Linux | Press `Control` + `Shift` + `J` +macOS | Press `Command` + `Option` + `J` +Windows | Press `Control` + `Shift` + `J` + +You can also open the developer console from the browser's menu: + +Browser | Menu path +------- | ------------ +Chrome | Click the ⋮ menu icon, then `More Tools` > `Developer Tools` +Edge | `Tools` > `Developer` > `JavaScript Console` +Firefox | Click the ☰ menu icon, then `More Tools` > `Developer Console` +Safari | `Develop` > `Show JavaScript Console`

    If you do not see the `Develop` option, open `Safari` > `Preferences` > `Advanced` and select the checkbox for `Show Develop menu in menu bar` + +Depending on your browser, the developer console may open in a separate browser window or within the current browser window as shown in this example: + +{{< figure src="/images/go/troubleshoot/web_ui_developer_console.png" alt="Developer console open in a Chrome browswer window displaying the web UI error message with options for clearing state and reloading." link="/images/go/troubleshoot/web_ui_developer_console.png" target="_blank" >}} + +The developer console lists all errors for the current page. +Click an error for more information about it. + +The developer console is part of web developer tools that are included in all modern browsers. +These tools may have different names in different browsers (for example, DevTools in Chrome and Developer Tools in Firefox), but they offer similar features. +Read the documentation for your browser to learn more about the web developer tools your browser provides. + + +[1]: ../../../observability-pipeline/observe-schedule/agent/ +[2]: ../../../platforms/#windows +[3]: ../../deploy-sensu/secure-sensu/#optional-configure-sensu-agent-mtls-authentication +[4]: https://etcd.io/docs/latest/op-guide/security/ +[5]: ../../../observability-pipeline/observe-schedule/agent/#restart-the-service +[6]: ../../../observability-pipeline/observe-schedule/agent#events-post +[7]: https://dzone.com/articles/what-is-structured-logging +[8]: https://pkgs.org/download/lsb +[9]: ../../../observability-pipeline/observe-schedule/backend/#restart-the-service +[10]: ../../../plugins/assets#asset-example-multiple-builds +[11]: ../../monitor-sensu/log-sensu-systemd/ +[12]: https://github.com/systemd/systemd/issues/2913 +[13]: https://github.com/etcd-io/etcd/releases +[14]: https://etcd.io/docs/latest/tuning/#disk +[15]: https://www.ibm.com/cloud/blog/using-fio-to-tell-whether-your-storage-is-fast-enough-for-etcd +[16]: ../../deploy-sensu/datastore/#scale-event-storage +[17]: ../../deploy-sensu/datastore/#use-default-event-storage +[18]: ../../../api/other/metrics/ +[19]: ../../deploy-sensu/hardware-requirements/#backend-recommended-configuration +[20]: ../../deploy-sensu/datastore/#round-robin-postgresql +[21]: https://www.computerhope.com/unix/sha512sum.htm +[22]: ../../../sensuctl/back-up-recover/ +[23]: ../../deploy-sensu/cluster-sensu/#sensu-backend-configuration +[24]: ../../../sensuctl/back-up-recover/#restore-resources-from-backup +[25]: ../../../observability-pipeline/observe-schedule/backend/#initialization +[26]: https://etcd.io/docs/latest/op-guide/recovery/#restoring-a-cluster +[27]: https://golang.google.cn/doc/go1.15#commonname +[28]: ../../deploy-sensu/generate-certificates/ +[29]: https://etcd.io/docs/latest/dev-guide/interacting_v3/ +[30]: ../../../observability-pipeline/observe-schedule/backend/ +[31]: ../../../observability-pipeline/observe-schedule/subscriptions/ diff --git a/content/sensu-go/6.12/operations/maintain-sensu/tune.md b/content/sensu-go/6.12/operations/maintain-sensu/tune.md new file mode 100644 index 0000000000..9d57246ea7 --- /dev/null +++ b/content/sensu-go/6.12/operations/maintain-sensu/tune.md @@ -0,0 +1,95 @@ +--- +title: "Tune Sensu" +linkTitle: "Tune Sensu" +description: "Learn when and how to tune Sensu to resolve performance issues, with links to more detailed documentation." +weight: 25 +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: maintain-sensu +--- + +This page describes tuning options that may help restore proper operation if you experience performance issues with your Sensu installation. + +{{% notice note %}} +**NOTE**: Before you tune your Sensu installation, read [Troubleshoot Sensu](../troubleshoot/), [Hardware requirements](../../deploy-sensu/hardware-requirements/), and [Deployment architecture for Sensu](../../deploy-sensu/deployment-architecture/). +These pages describe common problems and solutions, planning and optimization considerations, and other recommendations that may resolve your issue without tuning adjustments. +{{% /notice %}} + +## Latency tolerances for etcd + +If you use embedded etcd for storage, you might notice high network or storage latency. + +To make etcd more latency-tolerant, increase the values for the [`etcd election timeout`][1] and [`etcd heartbeat interval`][2] backend configuration options. +For example, you might increase `etcd-election-timeout` from 3000 to 5000 and `etcd-heartbeat-interval` from 300 to 500. + +Read the [etcd tuning documentation][3] for etcd-specific tuning best practices. + +## Advanced backend configuration options for etcd + +The [backend reference][11] describes other advanced configuration options in addition to etcd election timeout and heartbeat interval. + +Adjust these values with caution. +Improper adjustment can increase memory and CPU usage or result in a non-functioning Sensu instance. + +## Input/output operations per second (IOPS) + +The speed with which write operations can be completed is important to Sensu cluster performance and health. +Make sure to provision Sensu backend infrastructure to provide sustained input/output operations per second (IOPS) appropriate for the rate of observability events the system will be required to process. + +Read [Backend recommended configuration][12] and [Hardware sizing][13] for details. + +## PostgreSQL settings + +The [datastore reference][4] lists the PostgreSQL configuration parameters and settings we recommend as a starting point for your `postgresql.conf` file. +Adjust the parameters and settings as needed based on your hardware and performance observations. + +Read the [PostgreSQL parameters documentation][5] for information about setting parameters. + +## Agent reconnection rate + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access the `agent-rate-limit` backend configuration option in the packaged Sensu Go distribution. For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} + +It may take several minutes for all agents to reconnect after a sensu-backend restart, especially if you have a large number of agents. +The agent reconnection rate depends on deployment variables like the number of CPUs, disk space, network speeds, whether you're using a load balancer, and even physical distance between agents and backends. + +Although many variables affect the agent reconnection rate, a reasonable estimate is approximately 100 agents per backend per second. +If you observe slower agent reconnection rates in your Sensu deployment, consider using the [`agent-rate-limit`][14] backend configuration option. + +The [`agent-rate-limit`][14] backend configuration option allows you to set the maximum number of agent transport WebSocket connections per second, per backend. +Set the agent-rate-limit to 100 to improve agent reconnection rate and reduce the time required for all of your agents to reconnect after a backend restart. + +## Splay and proxy check scheduling + +Adjust the [`splay`][7] and [`splay_coverage`][8] check attributes to tune proxy check executions across an interval. +Read [Fine-tune proxy check scheduling with splay][9] for an example. + +## Tokens and resource re-use + +Tokens are placeholders in a check, hook, or dynamic runtime asset definition that the agent replaces with entity information before execution. +You can use tokens to fine-tune check, hook, and asset attributes on a per-entity level while reusing resource definitions. + +Read the [tokens reference][10] for token syntax and examples. + +## Occurrences and alert fatigue + +Use the [`occurrences` and `occurrences_watermark` event attributes][6] in event filters to tune incident notifications and reduce alert fatigue. + + +[1]: ../../../observability-pipeline/observe-schedule/backend/#etcd-election-timeout +[2]: ../../../observability-pipeline/observe-schedule/backend/#etcd-heartbeat-interval +[3]: https://etcd.io/docs/latest/tuning/ +[4]: ../../deploy-sensu/datastore/#postgresql-requirements +[5]: https://www.postgresql.org/docs/current/config-setting.html +[6]: ../../../observability-pipeline/observe-events/events/#occurrences-and-occurrences-watermark +[7]: ../../../observability-pipeline/observe-schedule/checks/#splay +[8]: ../../../observability-pipeline/observe-schedule/checks/#splay-coverage +[9]: ../../../observability-pipeline/observe-schedule/checks/#fine-tune-proxy-check-scheduling-with-splay +[10]: ../../../observability-pipeline/observe-schedule/tokens/ +[11]: ../../../observability-pipeline/observe-schedule/backend/#advanced-configuration-options +[12]: ../../deploy-sensu/hardware-requirements/#backend-recommended-configuration +[13]: ../../deploy-sensu/deployment-architecture/#hardware-sizing +[14]: ../../../observability-pipeline/observe-schedule/backend/#agent-rate-limit diff --git a/content/sensu-go/6.12/operations/maintain-sensu/upgrade.md b/content/sensu-go/6.12/operations/maintain-sensu/upgrade.md new file mode 100644 index 0000000000..f92420977d --- /dev/null +++ b/content/sensu-go/6.12/operations/maintain-sensu/upgrade.md @@ -0,0 +1,263 @@ +--- +title: "Upgrade Sensu" +linkTitle: "Upgrade Sensu" +description: "Upgrade to the latest version of Sensu. Read this upgrade guide to learn about the latest features and bug fixes in Sensu Go." +weight: 10 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: maintain-sensu +--- + +To upgrade to the latest version of Sensu Go: + +1. [Install or upgrade to][1] the latest packages or Docker image. + + {{% notice note %}} + **NOTE**: If you're upgrading a Sensu cluster, upgrade **all** of your Sensu backends before you run the `sensu-backend upgrade` command in step 5. +{{% /notice %}} + +2. For systems that use `systemd`, run: +{{< code shell >}} +sudo systemctl daemon-reload +{{< /code >}} + +3. Restart the Sensu agent: +{{< code shell >}} +sudo systemctl restart sensu-agent +{{< /code >}} + +4. Restart the Sensu backend: +{{< code shell >}} +sudo systemctl restart sensu-backend +{{< /code >}} + +5. Run a single upgrade command on one your Sensu backends to migrate the cluster: +{{< code shell >}} +sensu-backend upgrade +{{< /code >}} + + To skip confirmation and immediately run the upgrade command, add the `--skip-confirm` flag: +{{< code shell >}} +sensu-backend upgrade --skip-confirm +{{< /code >}} + + {{% notice note %}} + **NOTE**: If you are deploying a new Sensu cluster rather than upgrading from a previous version, you do not need to run the `sensu-backend upgrade` command. +{{% /notice %}} + +6. Enter `y` or `n` to confirm if you did *not* add the `--skip-confirm` flag in step 5. +Otherwise, skip this step. + +7. Wait a few seconds for the upgrade command to run. +You may notice some inconsistencies in your entity list until the cluster finishes upgrading. +Despite this, your cluster will continue to publish standard check requests and process events. + + If you run the upgrade command more than once, it will not harm the cluster — you'll just receive a response that the upgrade command has already been run. + + Some minor versions do not involve database-specific changes, and the `sensu-backend upgrade` tool will report that nothing was upgraded. +Check the [release notes][16] to confirm whether a version has database-specific changes that require a backend upgrade. + +8. Confirm the installed version for the agent, backend, and sensuctl: +{{< code shell >}} +sensu-agent version +{{< /code >}} +{{< code shell >}} +sensu-backend version +{{< /code >}} +{{< code shell >}} +sensuctl version +{{< /code >}} + +{{% notice protip %}} +**PRO TIP**: If your upgrade is unsuccessful, read the version-specific information on this page and complete the instructions for each version, starting with your current version and continuing up to the version you want to install.

    +For example, to debug an upgrade from 5.5.0 to 6.4.0, start with [Upgrade Sensu clusters from 5.7.0 or earlier to 5.8.0 or later](#upgrade-sensu-clusters-from-570-or-earlier-to-580-or-later). +{{% /notice %}} + +## Upgrade to Sensu Go 6.5.0 from any previous version + +To use [pipelines][18], you must upgrade your Sensu agents to Sensu Go 6.5.0. +Agents that are not upgraded to 6.5.0 will run checks, send observability events to the backend, and use the handlers that are defined in check [handlers arrays][17], but they will not run pipelines. + +## Upgrade to Sensu Go 6.4.0 from any previous version + +In Sensu Go 6.4.0, we upgraded the embedded etcd version from 3.3.22 to 3.5.0. +As a result, for deployments that use embedded etcd, 6.4.0 is not backward-compatible with previous versions of the Sensu backend. +In addition, Sensu 6.4.0 is not backward-compatible for PostgreSQL deployments. + +{{% notice note %}} +**NOTE**: Sensu Go 6.4.0 is backward-compatible for deployments that use external etcd, as well as with previous versions of the Sensu agent. +{{% /notice %}} + +For embedded etcd deployments, before you upgrade to Sensu Go 6.4.0, use the [etcd snapshot and restore process][9] to create a full etcd database backup. +If you use PostgreSQL, make sure to [back up your PostgreSQL database][13] also. + +If you make a full etcd database backup (and a PostgreSQL database backup, if you use PostgreSQL) before upgrading to 6.4.0, you will be able to restore your pre-6.4.0 deployment if you need to revert to an earlier Sensu release. + +After creating a full backup of your embedded etcd database and your PostgreSQL database, if you use PostgreSQL, you can complete the [upgrade process][10]. + +### CommonName deprecation in Go 1.15 + +Sensu Go 6.4.0 upgrades the Go version from 1.13.15 to 1.16.5. +As of [Go 1.15][11], certificates must include their CommonName (CN) as a Subject Alternative Name (SAN) field. + +To prevent connection errors after upgrading to Sensu Go 6.4.0, follow [Generate certificates][12] to make sure your certificates' SAN fields include their CNs. + +## Upgrade to Sensu Go 6.2.0 from any previous version + +Prior to Sensu Go 6.0, sensu-backend allowed you to delete a namespace even when other resources still referenced that namespace. +As of Sensu Go 6.0, it is not possible to delete namespaces that are referenced in other resources. +As a result, users whose configuration predates Sensu Go 6.0 may have lingering resources, including check configurations, that reference non-existent namespaces. + +Upgrading to Sensu Go 6.2.0 requires sensu-backend to upgrade check configurations. +If you have check configurations that reference non-existent namespaces, the 6.2.0 upgrade operation will fail when it encounters one of these check configurations. +You will receive an error message like this: + +{{< code text >}} +{"component":"store-providers","error":"the namespace test does not exist","level":"error","msg":"error enabling round robin scheduling,backend restart required","time":"2020-12-27T08:41:59Z"} +{{< /code >}} + +When this happens, the backend is effectively halted and subsequent restarts will result in the same state. + +### Remove checks that reference non-existent namespaces + +Use the following commands with the [jq utility][7] to identify and remove checks that reference deleted namespaces before you upgrade to Sensu Go 6.2.0. + +{{% notice note %}} +**NOTE**: If you have already upgraded to Sensu Go 6.2.0, you can work around this issue by temporarily reverting your Sensu instance to Sensu Go 6.1.4. +Then, recreate the missing namespaces referenced in your check configurations and upgrade again to 6.2.0. +{{% /notice %}} + +These commands use a Sensu backend running on `localhost` in the example URL and the environment variable $SENSU_API_KEY to represent a valid [API key][8]. + +1. Get a list of existing namespaces. +Run: +{{< code shell >}} +curl -s -H "Authorization: Key $SENSU_API_KEY" http://localhost:8080/api/core/v2/namespaces | jq '[.[].name]' +{{< /code >}} + + In this example, the existing namespaces are `stage` and `dev`. +{{< code text >}} +[ + "stage", + "dev" +] +{{< /code >}} + +2. Print the name and namespace for any checks that reference a namespace that is not specified in the jq expression on the same line (in this example, `["stage","dev"]`): +{{< code shell >}} +curl -s -H "Authorization: Key $SENSU_API_KEY" http://localhost:8080/api/core/v2/checks | jq '["stage","dev"] as $valid | .[] | select(.metadata.namespace as $in | $valid | index($in) | not) | {name: .metadata.name, namespace: .metadata.namespace}' +{{< /code >}} + + Your jq expression should include all of the namespaces you retrieved in step 1 (`stage` and `dev`). +{{< code text "JSON" >}} +{ + "name": "check-cpu", + "namespace": "test" +} +{{< /code >}} + +3. Recreate the missing `test` namespace so you can delete the `check-cpu` check. +{{< code shell >}} +sensuctl namespace create test +{{< /code >}} + +4. Delete the `check-cpu` check. +{{< code shell >}} +sensuctl check delete check-cpu --namespace test +{{< /code >}} + +5. Delete the `test` namespace, which is now empty after you deleted `check-cpu` in step 4. +{{< code shell >}} +sensuctl namespace delete test +{{< /code >}} + +After completing these commands, you can upgrade to 6.2.0. + +## Upgrade to Sensu Go 6.1.0 from 6.0.0 + +If you are using 6.0.0 and have a large number of events in PostgreSQL, you may experience a short period of unavailability after you upgrade to 6.1.0. +This pause will occur while the optimized selector information is populating during automatic database migration. +It may last for a period of a few seconds to a few minutes. + +This pause may extend to API request processing, so sensuctl and the web UI may also be unavailable during the migration. + +## Upgrade to Sensu Go 6.0 from a 5.x deployment + +Before you upgrade to Sensu 6.0, use [`sensuctl dump`][15] to create a backup of your existing installation. + +You will not be able to downgrade to a Sensu 5.x version after you upgrade your database to Sensu 6.0 after you restart the backend in the [upgrade process][10]. + +## Upgrade to Sensu Go 5.16.0 from any earlier version + +As of Sensu Go 5.16.0, Sensu's free entity limit is 100 entities. +All [commercial features][6] are available for free in the packaged Sensu Go distribution for up to 100 entities. + +When you upgrade to 5.16.0, if your existing unlicensed instance has more than 100 entities, Sensu will continue to monitor those entities. +However, if you try to create any new entities via the HTTP API or sensuctl, you will receive the following message: + +`This functionality requires a valid Sensu Go license with a sufficient entity limit. To get a valid license file, arrange a trial, or increase your entity limit, contact Sales.` + +Connections from new agents will fail and result in a log message like this: + +{{< code text >}} +{"component":"agent","error":"handshake failed with status 402","level":"error","msg":"reconnection attempt failed","time":"2019-11-20T05:49:24-07:00"} +{{< /code >}} + +In the web UI, you will receive the following message when you reach the 100-entity limit: + +{{< figure src="/images/go/upgrade/web_ui_entity_warning.png" alt="Example web UI warning message when you reach the 100-entity limit" link="/images/go/upgrade/web_ui_entity_warning.png" target="_blank" >}} + +If your Sensu instance includes more than 100 entities, [contact Sales][4] to learn how to upgrade your installation and increase your limit. +Read [our blog announcement][5] for more information about our usage policy. + +## Upgrade Sensu clusters from 5.7.0 or earlier to 5.8.0 or later + +{{% notice note %}} +**NOTE**: This section applies only to Sensu clusters with multiple backend nodes. +{{% /notice %}} + +Due to updates to etcd serialization, you must shut down Sensu clusters with multiple backend nodes while upgrading from Sensu Go 5.7.0 or earlier to 5.8.0 or later. +Read the [backend reference][2] for more information about stopping and starting backends. + +## Upgrade Sensu backend binaries to 5.1.0 + +{{% notice note %}} +**NOTE**: This section applies only to Sensu backend binaries downloaded from `s3-us-west-2.amazonaws.com/sensu.io/sensu-go`, not to Sensu RPM or DEB packages. +{{% /notice %}} + +For Sensu backend binaries, the default `state-dir` in 5.1.0 is now `/var/lib/sensu/sensu-backend` instead of `/var/lib/sensu`. +To upgrade your Sensu backend binary to 5.1.0, first [download the latest version][1]. +Then, make sure the `/etc/sensu/backend.yml` configuration file specifies a `state-dir`. +To continue using `/var/lib/sensu` as the `state-dir` to store backend data, add the following configuration to `/etc/sensu/backend.yml`: + +{{< code yml >}} +state-dir: "/var/lib/sensu" +{{< /code >}} + +Then restart the backend: + +{{< code shell >}} +sudo systemctl restart sensu-backend +{{< /code >}} + + +[1]: ../../deploy-sensu/install-sensu/ +[2]: ../../../observability-pipeline/observe-schedule/backend/ +[4]: https://sensu.io/contact?subject=contact-sales/ +[5]: https://sensu.io/blog/one-year-of-sensu-go +[6]: ../../../commercial/ +[7]: https://stedolan.github.io/jq/ +[8]: ../../../api/#authenticate-with-an-api-key +[9]: https://etcd.io/docs/latest/op-guide/recovery/ +[10]: ../../maintain-sensu/upgrade/ +[11]: https://golang.google.cn/doc/go1.15#commonname +[12]: ../../deploy-sensu/generate-certificates/ +[13]: https://www.postgresql.org/docs/current/backup.html +[14]: #upgrade-sensu-clusters-from-570-or-earlier-to-580-or-later +[15]: ../../../sensuctl/back-up-recover/ +[16]: ../../../release-notes/ +[17]: ../../../observability-pipeline/observe-schedule/checks#handlers-array +[18]: ../../../observability-pipeline/observe-process/pipelines/ diff --git a/content/sensu-go/6.12/operations/manage-secrets/_index.md b/content/sensu-go/6.12/operations/manage-secrets/_index.md new file mode 100644 index 0000000000..57d8e4ed44 --- /dev/null +++ b/content/sensu-go/6.12/operations/manage-secrets/_index.md @@ -0,0 +1,40 @@ +--- +title: "Manage Secrets" +description: "Sensu's secrets management allows you to avoid exposing secrets like usernames and passwords in your Sensu configuration." +product: "Sensu Go" +version: "6.12" +weight: 50 +layout: "single" +toc: true +menu: + sensu-go-6.12: + parent: operations + identifier: manage-secrets +--- + +Sensu's secrets management eliminates the need to expose secrets like usernames, passwords, and access keys in your Sensu configuration. +Secrets management is available for Sensu handler, mutator, and check resources. + +[Use secrets management in Sensu][1] explains how to use Sensu's secrets provider (`Env`), CyberArk Conjur, or HashiCorp Vault as your external secrets provider and authenticate without exposing your secrets. +Follow this guide to set up your PagerDuty Integration Key as a secret and create a PagerDuty handler definition that requires the secret. +Your Sensu backend will be able to execute the handler with any check. + +## Secrets + +Secrets are configured with Sensu's `Secret` resources. +A secret resource definition refers to the secrets provider and an ID (the named secret to fetch from the secrets provider). + +The [secrets reference][3] includes the specification, sensuctl configuration subcommands, and examples for secrets resources. + +## Secrets providers + +The [Sensu Go commercial distribution][2] includes a secrets provider, `Env`, that exposes secrets from environment variables on your Sensu backend nodes. +You can also use the `CyberArkProvider` type to authenticate via CyberArk Conjur or `VaultProvider` to authenticate via HashiCorp Vault. + +Read the [secrets providers reference][4] for Sensu resource specifications, instructions for retrieving your secrets providers configuration via the Sensu API, and examples. + + +[1]: secrets-management/ +[2]: ../../commercial/ +[3]: secrets/ +[4]: secrets-providers/ diff --git a/content/sensu-go/6.12/operations/manage-secrets/secrets-management.md b/content/sensu-go/6.12/operations/manage-secrets/secrets-management.md new file mode 100644 index 0000000000..4ac2984914 --- /dev/null +++ b/content/sensu-go/6.12/operations/manage-secrets/secrets-management.md @@ -0,0 +1,763 @@ +--- +title: "Use secrets management in Sensu" +linkTitle: "Use Secrets Management" +guide_title: "Use secrets management in Sensu" +type: "guide" +description: "Follow this guide to use Sensu's Env secrets provider, CyberArk Conjur, or HashiCorp Vault to avoid exposing sensitive information in your Sensu configuration." +weight: 10 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: manage-secrets +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access the Env, CyberArkProvider, and VaultProvider secrets provider datatypes in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} + +Sensu's secrets management allows you to avoid exposing secrets like usernames, passwords, and access keys in your Sensu configuration. +In this guide, you'll learn how to use Sensu's `Env` secrets provider, [CyberArk Conjur][42], or [HashiCorp Vault][1] as your external [secrets provider][2] and authenticate without exposing your secrets. +You'll set up your PagerDuty Integration Key as a secret, create a PagerDuty handler definition that requires the secret, and configure a pipeline that includes the PagerDuty handler. +Your Sensu backend can then execute the pipeline with any check. + +To follow this guide, [install the Sensu backend][5], make sure you have at least one [Sensu agent][11] running, and [install and configure sensuctl][7]. + +Secrets are configured via [secrets resources][8]. +A secret resource definition refers to the secrets provider (`Env`, `CyberArkProvider`, or `VaultProvider`) and an ID (the named secret to fetch from the secrets provider). + +This guide only covers the handler use case, but you can use secrets management in handler, mutator, and check execution. +When a check configuration references a secret, the Sensu backend will only transmit the check's execution requests to agents that are connected via [mutually authenticated transport layer security (mTLS)-encrypted WebSockets][15]. + +The secret included in your Sensu handler will be exposed to Sensu services at runtime as an environment variable. +Sensu only exposes secrets to Sensu services like environment variables and automatically redacts secrets from all logs, the API, and the web UI. + +## Retrieve your PagerDuty Integration Key + +The example in this guide uses the [PagerDuty][31] Integration Key as a secret and a PagerDuty handler definition that requires the secret. + +Here's how to find your Integration Key in PagerDuty so you can set it up as your secret: + +1. Log in to your PagerDuty account. +2. In the **Services** drop-down menu, select **Service Directory**. +3. Enter the name of your Sensu service in the search field. +4. Click to select your Sensu service from the list of search results. +5. Click the **Integrations** tab. +6. Click the drop-down arrow for the **Events API**. +The Integration Key is listed in the second field. + +{{< figure src="/images/go/secrets_management/location_pagerduty_integration_key.png" alt="PagerDuty Integration Key location" link="/images/go/secrets_management/location_pagerduty_integration_key.png" target="_blank" >}} + +Make a note of your Integration Key — you'll need it to create your backend environment variable or secret. + +Next, configure your secrets provider: + +- [Env][28] (Sensu's built-in secrets provider) +- [CyberArk Conjur][40] +- [HashiCorp Vault][29] + +## Use Env for secrets management + +The [Sensu Go commercial distribution][41] includes a secrets provider, `Env`, that exposes secrets from [environment variables][21] on your Sensu backend nodes. +The `Env` secrets provider is automatically created with an empty `spec` when you start your Sensu backend. + +### Create your backend environment variable + +To use the `Env` secrets provider, add your secret as a backend environment variable. + +First, make sure you have created the files you need to store [backend environment variables][21]. + +Then, run the following code, replacing `INTEGRATION_KEY` with your PagerDuty Integration Key: + +{{< language-toggle >}} + +{{< code shell "Debian family" >}} +echo 'SENSU_PAGERDUTY_KEY=INTEGRATION_KEY' | sudo tee -a /etc/default/sensu-backend +{{< /code >}} + +{{< code shell "RHEL family" >}} +echo 'SENSU_PAGERDUTY_KEY=INTEGRATION_KEY' | sudo tee -a /etc/sysconfig/sensu-backend +{{< /code >}} + +{{< /language-toggle >}} + +Restart the sensu-backend: + +{{< code shell >}} +sudo systemctl restart sensu-backend +{{< /code >}} + +This configures the `SENSU_PAGERDUTY_KEY` environment variable to your PagerDuty Integration Key in the context of the sensu-backend process. + +### Create your Env secret + +Now you'll use `sensuctl create` to create your secret. +This code creates a secret named `pagerduty_key` that refers to the environment variable ID `SENSU_PAGERDUTY_KEY`. +Run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +cat << EOF | sensuctl create +--- +type: Secret +api_version: secrets/v1 +metadata: + name: pagerduty_key +spec: + id: SENSU_PAGERDUTY_KEY + provider: env +EOF +{{< /code >}} + +{{< code shell "JSON" >}} +cat << EOF | sensuctl create +{ + "type": "Secret", + "api_version": "secrets/v1", + "metadata": { + "name": "pagerduty_key" + }, + "spec": { + "id": "SENSU_PAGERDUTY_KEY", + "provider": "env" + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + +You can securely pass your PagerDuty Integration Key in Sensu checks, handlers, and mutators by referring to the `pagerduty_key` secret. + +Continue to the [add a handler][19] section to use the `pagerduty_key` secret in your handler definition. + +## Use CyberArk Conjur for secrets management + +This section explains how to use [CyberArk Conjur][37] as your external [secrets provider][2]. + +Before you begin, follow the Conjur documentation to install and start the [Conjur OSS environment][38] and the [Conjur CLI][39]. + +### Create a Conjur account + +In the Conjur Docker container, run the following command to create a sensu.io account and initialize the admin user: + +{{< code shell >}} +docker-compose exec conjur conjurctl account create sensu.io +{{< /code >}} + +The response should confirm that Conjur created the sensu.io account and include an admin API key. +For example: + +{{< code text >}} +Created new account 'sensu.io' +Token-Signing Public Key: -----BEGIN PUBLIC KEY----- +MIIBIjANB... +-----END PUBLIC KEY----- +API key for admin: 5pj0kdx56npm8gksd9gre69sb21vh7zws2nk8jy73ekcyjk8e0xdj3 +{{< /code >}} + +### Write and load a Conjur policy with the secrets variable and host + +Use the [Conjur CLI][39] to load a policy and secrets for Sensu to use. + +1. Initialize the Conjur CLI client to use the sensu.io account and point it at the correct URL: + + {{< code shell >}} +conjur init -u conjur -a sensu.io +{{< /code >}} + + The response should confirm that initialization succeeded: + + {{< code text >}} +Wrote configuration to /root/.conjurrc +{{< /code >}} + +2. Write a Conjur policy that defines a human user, a non-human identity that represents a Sensu backend, at least one secret variable, permissions for the human user, and a host for the Sensu backend to use: + + {{< code shell >}} +cat << EOF > /tmp/policy.yaml +- !policy + id: Sensu + body: + - !user SensuAdmin + - !host sensuBackend + - !variable + id: pagerDutyAPIKey + - !permit + role: !user SensuAdmin + privileges: [read, update, execute] + resource: !variable pagerDutyAPIKey + - !permit + role: !host sensuBackend + privileges: [read, execute] + resource: !variable pagerDutyAPIKey +EOF +{{< /code >}} + +3. Load the policy: + + {{< code shell >}} +conjur policy load root /tmp/policy.yaml +{{< /code >}} + + {{% notice note %}} +**NOTE**: Conjur will prompt for your username and password. +Enter the username (`admin`) and password (the API key for admin) for the sensu.io account. +This information is included in the response to the command to [create a Conjur account](#create-a-conjur-account). +{{% /notice %}} + + The response should include a list of created roles and credentials, similar to this example: + + {{< code text >}} +Loaded policy 'root' +{ + "created_roles": { + "sensu.io:user:SensuAdmin@Sensu": { + "id": "sensu.io:user:SensuAdmin@Sensu", + "api_key": "25xjdpm21p3obl2yw7w4d1xmvzj32psjbps3ftaj1e32rb94y3q3xge1" + }, + "sensu.io:host:Sensu/sensuBackend": { + "id": "sensu.io:host:Sensu/sensuBackend", + "api_key": "2j78g5k0fb56fafsdoslehsaf246f092wmwkvh1qrgchk1tt8x8c" + } + }, + "version": 1 +} +{{< /code >}} + + Copy and save the API key value for the sensu.io:host:Sensu/sensuBackend role — you will need it when you create your CyberArkProvider secrets provider in Sensu. + +4. Use the Conjur CLI to set the pagerDutyAPIKey secret, replacing `` with your PagerDuty Integration Key: + + {{< code shell >}} +conjur variable values add Sensu/pagerDutyAPIKey +{{< /code >}} + + You should receive the response `Value added`. + +### Create your Conjur secrets provider + +Use `sensuctl create` to create your secrets provider, `conjur`. +In the code below, replace `` with the API key value for the sensu.io:host:Sensu/sensuBackend role. +Then, run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +cat << EOF | sensuctl create +--- +type: CyberArkProvider +api_version: secrets/v1 +metadata: + name: conjur +spec: + client: + account: sensu.io + appliance_url: http://localhost:8480 + login: host/Sensu/sensuBackend + api_key: + timeout: 1s + ttl: 60s +EOF +{{< /code >}} + +{{< code shell "JSON" >}} +cat << EOF | sensuctl create +{ + "type": "CyberArkProvider", + "api_version": "secrets/v1", + "metadata": { + "name": "conjur" + }, + "spec": { + "client": { + "account": "sensu.io", + "appliance_url": "http://localhost:8480", + "login": "host/Sensu/sensuBackend", + "api_key": "", + "timeout": "1s", + "ttl": "60s" + } + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + +### Create your Conjur secret + +Use `sensuctl create` to create your secret: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +cat << EOF | sensuctl create +--- +type: Secret +api_version: secrets/v1 +metadata: + name: pagerduty_key +spec: + provider: conjur + id: Sensu/pagerDutyAPIKey +EOF +{{< /code >}} + +{{< code shell "JSON" >}} +cat << EOF | sensuctl create +{ + "type": "Secret", + "api_version": "secrets/v1", + "metadata": { + "name": "pagerduty_key" + }, + "spec": { + "provider": "conjur", + "id": "Sensu/pagerDutyAPIKey" + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + +Now you can securely pass your PagerDuty Integration Key in the handlers and mutators by referring to the `pagerduty_key` secret. + +Continue to the [add a handler][19] section to use the `pagerduty_key` secret in your handler definition. + +## Use HashiCorp Vault for secrets management + +This section explains how to use [HashiCorp Vault][1] as your external [secrets provider][2] to authenticate via the HashiCorp Vault integration's [token auth method][3] or [TLS certificate auth method][4]. + +{{% notice note %}} +**NOTE**: You must set up [HashiCorp Vault](https://www.vaultproject.io/docs/install/) to use `VaultProvider` secrets management in production. +The examples in this guide use the [Vault dev server](https://www.vaultproject.io/docs/concepts/dev-server/), which is useful for learning and experimenting. +The Vault dev server gives you access to a preconfigured, running Vault server with in-memory storage that you can use right away. +Follow the [HashiCorp Learn curriculum](https://learn.hashicorp.com/vault) when you are ready to set up a production server in Vault.

    +In addition, this guide uses the [Vault KV secrets engine](https://www.vaultproject.io/api/secret/kv/kv-v2.html). +Using the Vault KV secrets engine with the Vault dev server requires v2 connections. +For this reason, in the `VaultProvider` spec in these examples, the client `version` value is **v2**. +{{% /notice %}} + +### Configure your Vault authentication method (token or TLS) + +If you use [HashiCorp Vault][1] as your external [secrets provider][2], you can authenticate via the HashiCorp Vault integration's [token][3] or [transport layer security (TLS) certificate][4] authentication method. + +#### Vault token authentication + +Follow the steps in this section to use HashiCorp Vault as your external [secrets provider][2] to authenticate with the HashiCorp Vault integration's [token auth method][3]. + +##### Retrieve your Vault root token + +{{% notice note %}} +**NOTE**: The examples in this guide use the `Root Token` for the the [Vault dev server](https://learn.hashicorp.com/vault/getting-started/dev-server), which gives you access to a preconfigured, running Vault server with in-memory storage that you can use right away. +Follow the [HashiCorp Learn curriculum](https://learn.hashicorp.com/vault) when you are ready to set up a production server in Vault. +{{% /notice %}} + +To retrieve your Vault root token: + +1. [Download and install][25] the Vault edition for your operating system. +2. Open a terminal window and run `vault server -dev`. + +The command output includes a `Root Token` line. +Find this line in your command output and copy the `Root Token` value. +You will use it next to create your Vault secrets provider. + +{{< figure src="/images/go/secrets_management/location_vault_dev_root_token.png" alt="HashiCorp Vault Root Token location" link="/images/go/secrets_management/location_vault_dev_root_token.png" target="_blank" >}} + +Leave the Vault dev server running. +Because you aren't using TLS, you will need to set `VAULT_ADDR=http://127.0.0.1:8200` in your shell environment. + +##### Create your Vault secrets provider + +{{% notice note %}} +**NOTE**: In Vault's dev server, TLS is not enabled, so you won't be able to use certificate-based authentication. +{{% /notice %}} + +Use `sensuctl create` to create your secrets provider, `vault`. +In the code below, replace `` with the `Root Token` value for your Vault dev server. +Then, run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +cat << EOF | sensuctl create +--- +type: VaultProvider +api_version: secrets/v1 +metadata: + name: vault +spec: + client: + address: http://localhost:8200 + token: + version: v2 + tls: null + max_retries: 2 + timeout: 20s + rate_limiter: + limit: 10 + burst: 100 +EOF +{{< /code >}} + +{{< code shell "JSON" >}} +cat << EOF | sensuctl create +{ + "type": "VaultProvider", + "api_version": "secrets/v1", + "metadata": { + "name": "vault" + }, + "spec": { + "client": { + "address": "http://localhost:8200", + "token": "", + "version": "v2", + "tls": null, + "max_retries": 2, + "timeout": "20s", + "rate_limiter": { + "limit": 10, + "burst": 100 + } + } + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + +To continue, skip ahead to [create your Vault secret][29]. + +#### Vault TLS certificate authentication + +This section explains how use HashiCorp Vault as your external [secrets provider][2] to authenticate with the HashiCorp Vault integration's [TLS certificate auth method][4]. + +{{% notice note %}} +**NOTE**: You will need to set up [HashiCorp Vault](https://www.vaultproject.io/docs/install/) in production to use TLS certificate-based authentication. +In Vault's dev server, TLS is not enabled. +Follow the [HashiCorp Learn curriculum](https://learn.hashicorp.com/vault) when you are ready to set up a production server in Vault. +{{% /notice %}} + +First, in your Vault, [enable and configure certificate authentication][32]. +For example, your Vault might be configured for certificate authentication like this: + +{{< code shell >}} +vault write auth/cert/certs/sensu-backend \ + display_name=sensu-backend \ + policies=sensu-backend-policy \ + certificate=@sensu-backend-vault.pem \ + ttl=3600 +{{< /code >}} + +Second, configure your `VaultProvider` in Sensu: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: VaultProvider +api_version: secrets/v1 +metadata: + name: vault +spec: + client: + address: https://vault.example.com:8200 + version: v2 + tls: + ca_cert: /path/to/your/ca.pem + client_cert: /etc/sensu/ssl/sensu-backend-vault.pem + client_key: /etc/sensu/ssl/sensu-backend-vault-key.pem + cname: sensu-backend.example.com + max_retries: 2 + timeout: 20s + rate_limiter: + limit: 10 + burst: 100 +{{< /code >}} + +{{< code shell "JSON" >}} +{ + "type": "VaultProvider", + "api_version": "secrets/v1", + "metadata": { + "name": "vault" + }, + "spec": { + "client": { + "address": "https://vault.example.com:8200", + "version": "v2", + "tls": { + "ca_cert": "/path/to/your/ca.pem", + "client_cert": "/etc/sensu/ssl/sensu-backend-vault.pem", + "client_key": "/etc/sensu/ssl/sensu-backend-vault-key.pem", + "cname": "sensu-backend.example.com" + }, + "max_retries": 2, + "timeout": "20s", + "rate_limiter": { + "limit": 10, + "burst": 100 + } + } + } +} +{{< /code >}} + +{{< /language-toggle >}} + +The certificate you specify for `tls.client_cert` should be the same certificate you configured in your Vault for certificate authentication. + +Next, [create your Vault secret][29]. + +### Create your Vault secret + +First, retrieve your [PagerDuty Integration Key][30] (the secret you will set up in Vault). + +Next, open a new terminal and run `vault kv put secret/pagerduty key=`. +Replace `` with your PagerDuty Integration Key. +This writes your secret into Vault. + +In this example, the name of the secret is `pagerduty`. +The `pagerduty` secret contains a key, and you specified that the `key` value is your PagerDuty Integration Key. + +{{% notice note %}} +**NOTE**: The Vault dev server is preconfigured with the secret keyspace already set up, so we recommend using the `secret/` path for the `id` value while you are learning and getting started with Vault secrets management.

    This example uses the `id` format for the Vault [KV Secrets Engine v1](https://www.vaultproject.io/api-docs/secret/kv/kv-v1): `secret/pagerduty#key`. +If you are using the Vault [KV Secrets Engine v2](https://www.vaultproject.io/api-docs/secret/kv/kv-v2), the format is `secrets/sensu#pagerduty#key`. + +{{% /notice %}} + +Run `vault kv get secret/pagerduty` to view the secret you just set up. + +Use `sensuctl create` to create your `vault` secret: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +cat << EOF | sensuctl create +--- +type: Secret +api_version: secrets/v1 +metadata: + name: pagerduty_key +spec: + id: secret/pagerduty#key + provider: vault +EOF +{{< /code >}} + +{{< code shell "JSON" >}} +cat << EOF | sensuctl create +{ + "type": "Secret", + "api_version": "secrets/v1", + "metadata": { + "name": "pagerduty_key" + }, + "spec": { + "id": "secret/pagerduty#key", + "provider": "vault" + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + +Now you can securely pass your PagerDuty Integration Key in the handlers, and mutators by referring to the `pagerduty_key` secret. + +Continue to the [add a handler][19] section to use the `pagerduty_key` secret in your handler definition. + +## Add a handler + +### Register the sensu/sensu-pagerduty-handler dynamic runtime asset + +To begin, register the [sensu/sensu-pagerduty-handler][23] dynamic runtime asset with [`sensuctl asset add`][22]: + +{{< code shell >}} +sensuctl asset add sensu/sensu-pagerduty-handler:2.2.0 -r pagerduty-handler +{{< /code >}} + +This example uses the `-r` (rename) flag to specify a shorter name for the dynamic runtime asset: `pagerduty-handler`. + +{{% notice note %}} +**NOTE**: You can [adjust the dynamic runtime asset definition](../../../plugins/use-assets-to-install-plugins#adjust-the-asset-definition) according to your Sensu configuration if needed. +{{% /notice %}} + +Run `sensuctl asset list --format yaml` to confirm that the dynamic runtime asset is ready to use. + +With this handler, Sensu can trigger and resolve PagerDuty incidents. +However, you still need to add your secret to the handler spec so that it requires your backend to request secrets from your secrets provider. + +### Add your secret to the handler spec + +To create a handler definition that uses your `pagerduty_key` secret, run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +cat << EOF | sensuctl create +--- +api_version: core/v2 +type: Handler +metadata: + name: pagerduty +spec: + type: pipe + command: pagerduty-handler --token $PD_TOKEN + secrets: + - name: PD_TOKEN + secret: pagerduty_key + runtime_assets: + - pagerduty-handler + timeout: 10 +EOF +{{< /code >}} + +{{< code shell "JSON" >}} +cat << EOF | sensuctl create +{ + "api_version": "core/v2", + "type": "Handler", + "metadata": { + "name": "pagerduty" + }, + "spec": { + "type": "pipe", + "command": "pagerduty-handler --token $PD_TOKEN", + "secrets": [ + { + "name": "PD_TOKEN", + "secret": "pagerduty_key" + } + ], + "runtime_assets": [ + "pagerduty-handler" + ], + "timeout": 10 + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + +## Configure a pipeline + +Now that your handler is set up and Sensu can create incidents in PagerDuty, you can configure a [pipeline][33] to start receiving alerts based on the events your checks create. +A single pipeline workflow can include one or more filters, one mutator, and one handler. + +In this case, the pipeline will include the built-in [is_incident][34] event filter and the `pagerduty` handler you created in the previous step. +You can add this pipeline to any check to receive a PagerDuty alert for every warning (`1`) or critical (`2`) event the check generates, as well as for resolution events. + +To create the pipeline, run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +cat << EOF | sensuctl create +--- +type: Pipeline +api_version: core/v2 +metadata: + name: incident_alerts +spec: + workflows: + - name: pagerduty_incidents + filters: + - name: is_incident + type: EventFilter + api_version: core/v2 + handler: + name: pagerduty + type: Handler + api_version: core/v2 +EOF +{{< /code >}} + +{{< code shell "JSON" >}} +cat << EOF | sensuctl create +{ + "type": "Pipeline", + "api_version": "core/v2", + "metadata": { + "name": "incident_alerts" + }, + "spec": { + "workflows": [ + { + "name": "pagerduty_incidents", + "filters": [ + { + "name": "is_incident", + "type": "EventFilter", + "api_version": "core/v2" + } + ], + "handler": { + "name": "pagerduty", + "type": "Handler", + "api_version": "core/v2" + } + } + ] + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + +To automate this workflow, include the `incident_alerts` pipeline in any Sensu check definition in the check's [pipelines attribute][24]. +When you list a pipeline in a check definition, all the observability events that the check produces will be processed according to the pipeline’s [workflows][35]. + +## Next steps + +Add your pipeline to any check to start receiving PagerDuty alerts based on observability event data. +Read [Send PagerDuty alerts with Sensu][36] for an example that shows how to edit a check definition to add a pipeline. + +Read the [secrets][9] or [secrets providers][2] reference for in-depth secrets management documentation. + + +[1]: https://www.vaultproject.io/docs/what-is-vault/ +[2]: ../../../operations/manage-secrets/secrets-providers/ +[3]: https://www.vaultproject.io/docs/auth/token/ +[4]: https://www.vaultproject.io/docs/auth/cert/ +[5]: ../../deploy-sensu/install-sensu/#install-the-sensu-backend +[6]: ../../deploy-sensu/install-sensu/#install-sensu-agents +[7]: ../../deploy-sensu/install-sensu/#install-sensuctl +[8]: ../../../api/enterprise/secrets/ +[9]: ../../../operations/manage-secrets/secrets/ +[11]: ../../deploy-sensu/install-sensu/#install-sensu-agents +[12]: https://www.vaultproject.io/docs/concepts/lease.html#lease-durations-and-renewal +[13]: ../../../api/enterprise/secrets/#providers-provider-put +[14]: ../../../api/enterprise/secrets/#secrets-secret-put +[15]: ../../deploy-sensu/secure-sensu/#optional-configure-sensu-agent-mtls-authentication +[17]: ../../../operations/manage-secrets/secrets-providers#tls-vault +[19]: #add-a-handler +[21]: ../../../observability-pipeline/observe-schedule/backend/#environment-variables +[22]: ../../../sensuctl/sensuctl-bonsai/#install-dynamic-runtime-asset-definitions +[23]: https://bonsai.sensu.io/assets/sensu/sensu-pagerduty-handler +[24]: ../../../observability-pipeline/observe-schedule/checks/#pipelines-attribute +[25]: https://www.vaultproject.io/downloads/ +[28]: #use-env-for-secrets-management +[29]: #use-hashicorp-vault-for-secrets-management +[30]: #retrieve-your-pagerduty-integration-key +[31]: https://www.pagerduty.com/ +[32]: https://www.vaultproject.io/docs/auth/cert/#configuration +[33]: ../../../observability-pipeline/observe-process/pipelines/ +[34]: ../../../observability-pipeline/observe-filter/filters/#built-in-filter-is_incident +[35]: ../../../observability-pipeline/observe-process/pipelines/#workflows +[36]: ../../../observability-pipeline/observe-process/send-pagerduty-alerts/#assign-the-pipeline-to-a-check +[37]: https://www.conjur.org/ +[38]: https://www.conjur.org/get-started/quick-start/oss-environment/ +[39]: https://docs.conjur.org/Latest/en/Content/Developer/CLI/cli-lp.htm?tocpath=Developer%7CConjur%20CLI%7C_____0 +[40]: #use-cyberark-conjur-for-secrets-management +[41]: ../../../commercial/ +[42]: https://www.conjur.org/ diff --git a/content/sensu-go/6.12/operations/manage-secrets/secrets-providers.md b/content/sensu-go/6.12/operations/manage-secrets/secrets-providers.md new file mode 100644 index 0000000000..6fbceb0d29 --- /dev/null +++ b/content/sensu-go/6.12/operations/manage-secrets/secrets-providers.md @@ -0,0 +1,731 @@ +--- +title: "Secrets providers reference" +linkTitle: "Secrets Providers Reference" +reference_title: "Secrets providers" +type: "reference" +description: "Avoid exposing sensitive information like usernames, passwords, and access keys in your Sensu configuration with Sensu's secrets management feature." +weight: 30 +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: manage-secrets +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access the `Env`, `CyberArkProvider`, and `VaultProvider` secrets provider datatypes in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} + +Sensu's secrets management eliminates the need to expose secrets like usernames, passwords, and access keys in your Sensu configuration. +With Sensu's secrets management, you can obtain secrets from one or more external secrets providers, refer to external secrets, and consume secrets via [backend environment variables][4]. + +{{% notice note %}} +**NOTE**: Secrets management is implemented for [checks](../../../observability-pipeline/observe-schedule/checks/#check-example-that-uses-secrets-management), [handlers](../../../observability-pipeline/observe-process/handlers/#use-secrets-management-in-a-handler), and [mutators](../../../observability-pipeline/observe-transform/mutators/#use-secrets-management-in-a-mutator). +{{% /notice %}} + +Only Sensu backends have access to request [secrets][9] from a secrets provider. +Secrets are only transmitted over a transport layer security (TLS) WebSocket connection. +Unencrypted connections must not transmit privileged information. +For checks, hooks, and dynamic runtime assets, you must [enable mutual TLS (mTLS)][13]. +Sensu will not transmit secrets to agents that do not use mTLS. + +The [Sensu Go commercial distribution][1] includes a secrets provider, `Env`, that exposes secrets from [environment variables][4] on your Sensu backend nodes. +You can also use the `CyberArkProvider` and `VaultProvider` secrets providers. + +You can configure any number of `CyberArkProvider` and `VaultProvider` secrets providers. +However, you can only have a single `Env` secrets provider: the one that is included with the Sensu Go [commercial distribution][1]. + +Secrets providers are cluster-wide resources and compatible with generic functions. + +## Env secrets provider example + +Sensu's `Env` secrets provider exposes secrets from [backend environment variables][4]. +The `Env` secrets provider is automatically created with an empty `spec` when you start your Sensu backend. + +Using the `Env` secrets provider may require you to synchronize environment variables in Sensu backend clusters. +Read [Use secrets management][16] to learn how to configure the `Env` secrets provider. + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Env +api_version: secrets/v1 +metadata: + name: env +spec: {} +{{< /code >}} + +{{< code json >}} +{ + "type": "Env", + "api_version": "secrets/v1", + "metadata": { + "name": "env" + }, + "spec": {} +} +{{< /code >}} + +{{< /language-toggle >}} + +## CyberArkProvider secrets provider example + +The `CyberArkProvider` secrets provider is a vendor-specific implementation for [CyberArk Conjur][18] secrets management. + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: CyberArkProvider +api_version: secrets/v1 +metadata: + name: cyberark +spec: + client: + account: sensu.io + appliance_url: http://localhost:8480 + login: host/Sensu/sensuBackend + api_key: CONJUR_API_KEY + timeout: 1s + tls: + ca_cert: "/etc/ssl/certs/conjur_ca_cert.pem" + ttl: 60s +{{< /code >}} + +{{< code json >}} +{ + "type": "CyberArkProvider", + "api_version": "secrets/v1", + "metadata": { + "name": "cyberark" + }, + "spec": { + "client": { + "account": "sensu.io", + "appliance_url": "http://localhost:8480", + "login": "host/Sensu/sensuBackend", + "api_key": "CONJUR_API_KEY", + "timeout": "1s", + "tls": { + "ca_cert": "/etc/ssl/certs/conjur_ca_cert.pem" + }, + "ttl": "60s" + } + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## VaultProvider secrets provider example + +The `VaultProvider` secrets provider is a vendor-specific implementation for [HashiCorp Vault][5] secrets management. + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: VaultProvider +api_version: secrets/v1 +metadata: + name: vault +spec: + client: + address: https://vaultserver.example.com:8200 + token: VAULT_TOKEN + version: v1 + tls: + ca_cert: "/etc/ssl/certs/vault_ca_cert.pem" + max_retries: 2 + timeout: 20s + rate_limiter: + limit: 10 + burst: 100 +{{< /code >}} + +{{< code json >}} +{ + "type": "VaultProvider", + "api_version": "secrets/v1", + "metadata": { + "name": "vault" + }, + "spec": { + "client": { + "address": "https://vaultserver.example.com:8200", + "token": "VAULT_TOKEN", + "version": "v1", + "tls": { + "ca_cert": "/etc/ssl/certs/vault_ca_cert.pem" + }, + "max_retries": 2, + "timeout": "20s", + "rate_limiter": { + "limit": 10.0, + "burst": 100 + } + } + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Secrets provider configuration + +You can use the [enterprise/secrets/v1 API endpoints][2] to create, view, and manage your secrets provider configuration. + +For example, to retrieve the list of secrets providers: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/api/enterprise/secrets/v1/providers \ +-H "Authorization: Key $SENSU_API_KEY" +{{< /code >}} + +## Secrets provider specification + +{{% notice note %}} +**NOTE**: The attribute descriptions in this section use the `CyberArkProvider` and `VaultProvider` datatypes. +Review the [Env secrets provider example](#env-secrets-provider-example) for an example definition for the `Env` datatype. +{{% /notice %}} + +### Top-level attributes + +api_version | +-------------|------ +description | Top-level attribute that specifies the Sensu API group and version. For secrets configuration in this version of Sensu, the api_version should always be `secrets/v1`. +required | Required for secrets configuration in `wrapped-json` or `yaml` format. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +api_version: secrets/v1 +{{< /code >}} +{{< code json >}} +{ + "api_version": "secrets/v1" +} +{{< /code >}} +{{< /language-toggle >}} + +metadata | | +-------------|------ +description | Top-level scope that contains the secrets provider `name` and `created_by` field. Namespace is not supported in the metadata because secrets providers are cluster-wide resources. +required | true +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +metadata: + name: vault + created_by: admin +{{< /code >}} +{{< code json >}} +{ + "metadata": { + "name": "vault", + "created_by": "admin" + } +} +{{< /code >}} +{{< /language-toggle >}} + +spec | +-------------|------ +description | Top-level map that includes secrets provider configuration spec attributes. Read [VaultProvider spec attributes][8] and [CyberArkProvider spec attributes][19] for details. +required | Required for secrets configuration in `wrapped-json` or `yaml` format. +type | Map of key-value pairs +CyberArkProvider example | {{< language-toggle >}} +{{< code yml >}} +spec: + client: + account: sensu.io + appliance_url: http://localhost:8480 + login: host/Sensu/sensuBackend + api_key: CONJUR_API_KEY + timeout: 1s + tls: + ca_cert: "/etc/ssl/certs/conjur_ca_cert.pem" + ttl: 60s +{{< /code >}} +{{< code json >}} +{ + "spec": { + "client": { + "account": "sensu.io", + "appliance_url": "http://localhost:8480", + "login": "host/Sensu/sensuBackend", + "api_key": "CONJUR_API_KEY", + "timeout": "1s", + "tls": { + "ca_cert": "/etc/ssl/certs/conjur_ca_cert.pem" + }, + "ttl": "60s" + } + } +} +{{< /code >}} +{{< /language-toggle >}} +VaultProvider example | {{< language-toggle >}} +{{< code yml >}} +spec: + client: + address: https://vaultserver.example.com:8200 + max_retries: 2 + rate_limiter: + limit: 10 + burst: 100 + timeout: 20s + tls: + ca_cert: "/etc/ssl/certs/vault_ca_cert.pem" + token: VAULT_TOKEN + version: v1 +{{< /code >}} +{{< code json >}} +{ + "spec": { + "client": { + "address": "https://vaultserver.example.com:8200", + "max_retries": 2, + "rate_limiter": { + "limit": 10, + "burst": 100 + }, + "timeout": "20s", + "tls": { + "ca_cert": "/etc/ssl/certs/vault_ca_cert.pem" + }, + "token": "VAULT_TOKEN", + "version": "v1" + } + } +} +{{< /code >}} +{{< /language-toggle >}} + +type | +-------------|------ +description | Top-level attribute that specifies the resource type. +required | Required for secrets configuration in `wrapped-json` or `yaml` format. +type | String +allowed values | - `Env` if using Sensu's secrets provider
    - `CyberArkProvider` if using CyberArk Conjur as the secrets provider
    - `VaultProvider` if using HashiCorpVault as the secrets provider +example | {{< language-toggle >}} +{{< code yml >}} +type: VaultProvider +{{< /code >}} +{{< code json >}} +{ + "type": "VaultProvider" +} +{{< /code >}} +{{< /language-toggle >}} + +### Metadata attributes + +| created_by | | +-------------|------ +description | Username of the Sensu user who created the secrets provider or last updated the secrets provider. Sensu automatically populates the `created_by` field when the secrets provider is created or updated. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +created_by: admin +{{< /code >}} +{{< code json >}} +{ + "created_by": "admin" +} +{{< /code >}} +{{< /language-toggle >}} + +name | | +-------------|------ +description | Provider name used internally by Sensu. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +name: vault +{{< /code >}} +{{< code json >}} +{ + "name": "vault" +} +{{< /code >}} +{{< /language-toggle >}} + +### CyberArkProvider spec attributes + +client | +-------------|------ +description | Map that includes [CyberArkProvider client attributes][20]. +required | true +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +client: + account: sensu.io + appliance_url: http://localhost:8480 + login: host/Sensu/sensuBackend + api_key: CONJUR_API_KEY + timeout: 1s + tls: + ca_cert: "/etc/ssl/certs/conjur_ca_cert.pem" + ttl: 60s +{{< /code >}} +{{< code json >}} +{ + "client": { + "account": "sensu.io", + "appliance_url": "http://localhost:8480", + "login": "host/Sensu/sensuBackend", + "api_key": "CONJUR_API_KEY", + "timeout": "1s", + "tls": { + "ca_cert": "/etc/ssl/certs/conjur_ca_cert.pem" + }, + "ttl": "60s" + } +} +{{< /code >}} +{{< /language-toggle >}} + +#### CyberArkProvider client attributes + +account | +-------------|------ +description | Conjur account name. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +account: sensu.io +{{< /code >}} +{{< code json >}} +{ + "account": "sensu.io" +} +{{< /code >}} +{{< /language-toggle >}} + +appliance_url | +--------------|------ +description | Conjur appliance URL (the HTTP or HTTPS endpoint CyberArk listens on). +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +appliance_url: http://localhost:8480 +{{< /code >}} +{{< code json >}} +{ + "appliance_url": "http://localhost:8480" +} +{{< /code >}} +{{< /language-toggle >}} + +login | +-------------|------ +description | Conjur authentication login. The login includes `host` followed by the values provided for id and host in the Conjur policy: `host//` +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +login: host/Sensu/sensuBackend +{{< /code >}} +{{< code json >}} +{ + "login": "host/Sensu/sensuBackend" +} +{{< /code >}} +{{< /language-toggle >}} + +timeout | +-------------|------ +description | Provider connection timeout (hard stop). +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +timeout: 1s +{{< /code >}} +{{< code json >}} +{ + "timeout": "1s" +} +{{< /code >}} +{{< /language-toggle >}} + + + +tls | +-------------|------ +description | TLS object. You may need to set up a Certificate Authority (CA) certificate if it is not already stored in your operating system's trust store. To do this, set the TLS object and provide the `ca_cert` path. You may also need to set up `client_cert`, `client_key`, or `cname`. +required | false +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +tls: + ca_cert: "/etc/ssl/certs/conjur_ca_cert.pem" + client_cert: "/etc/ssl/certs/conjur_cert.pem" + client_key: "/etc/ssl/certs/conjur_key.pem" + cname: conjur_client.example.com +{{< /code >}} +{{< code json >}} +{ + "tls": { + "ca_cert": "/etc/ssl/certs/conjur_ca_cert.pem", + "client_cert": "/etc/ssl/certs/conjur_cert.pem", + "client_key": "/etc/ssl/certs/conjur_key.pem", + "cname": "conjur_client.example.com" + } +} +{{< /code >}} +{{< /language-toggle >}} + +ttl | +-------------|------ +description | The time-to-live (TTL) until CyberArkProvider secrets are considered stale. Sensu will cache secrets provider values for this duration. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +ttl: 1s +{{< /code >}} +{{< code json >}} +{ + "ttl": "1s" +} +{{< /code >}} +{{< /language-toggle >}} + +### VaultProvider spec attributes + +client | +-------------|------ +description | Map that includes [VaultProvider client attributes][12]. +required | true +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +client: + address: https://vaultserver.example.com:8200 + max_retries: 2 + rate_limiter: + limit: 10 + burst: 100 + timeout: 20s + tls: + ca_cert: "/etc/ssl/certs/vault_ca_cert.pem" + token: VAULT_TOKEN + version: v1 +{{< /code >}} +{{< code json >}} +{ + "client": { + "address": "https://vaultserver.example.com:8200", + "max_retries": 2, + "rate_limiter": { + "limit": 10, + "burst": 100 + }, + "timeout": "20s", + "tls": { + "ca_cert": "/etc/ssl/certs/vault_ca_cert.pem" + }, + "token": "VAULT_TOKEN", + "version": "v1" + } +} +{{< /code >}} +{{< /language-toggle >}} + +#### VaultProvider client attributes + +address | +-------------|------ +description | Vault server address. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +address: https://vaultserver.example.com:8200 +{{< /code >}} +{{< code json >}} +{ + "address": "https://vaultserver.example.com:8200" +} +{{< /code >}} +{{< /language-toggle >}} + +max_retries | +-------------|------ +description | Number of times to retry connecting to the Vault provider. +required | true +type | Integer +default | 2 +example | {{< language-toggle >}} +{{< code yml >}} +max_retries: 2 +{{< /code >}} +{{< code json >}} +{ + "max_retries": 2 +} +{{< /code >}} +{{< /language-toggle >}} + +rate_limiter | +-------------|------ +description | Maximum rate and burst limits for the [enterprise/secrets/v1][2] API endpoint. Read [rate_limiter attributes][17] for more information. +required | false +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +rate_limiter: + limit: 10 + burst: 100 +{{< /code >}} +{{< code json >}} +{ + "rate_limiter": { + "limit": 10, + "burst": 100 + } +} +{{< /code >}} +{{< /language-toggle >}} + +timeout | +-------------|------ +description | Provider connection timeout (hard stop). +required | false +type | String +default | 60s +example | {{< language-toggle >}} +{{< code yml >}} +timeout: 20s +{{< /code >}} +{{< code json >}} +{ + "timeout": "20s" +} +{{< /code >}} +{{< /language-toggle >}} + + + +tls | +-------------|------ +description | TLS object. Vault only works with TLS configured. You may need to set up a Certificate Authority (CA) certificate if it is not already stored in your operating system's trust store. To do this, set the TLS object and provide the `ca_cert` path. You may also need to set up `client_cert`, `client_key`, or [`cname`][15]. +required | false +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +tls: + ca_cert: "/etc/ssl/certs/vault_ca_cert.pem" + client_cert: "/etc/ssl/certs/vault_cert.pem" + client_key: "/etc/ssl/certs/vault_key.pem" + cname: vault_client.example.com +{{< /code >}} +{{< code json >}} +{ + "tls": { + "ca_cert": "/etc/ssl/certs/vault_ca_cert.pem", + "client_cert": "/etc/ssl/certs/vault_cert.pem", + "client_key": "/etc/ssl/certs/vault_key.pem", + "cname": "vault_client.example.com" + } +} +{{< /code >}} +{{< /language-toggle >}} + +token | +-------------|------ +description | Vault token to use for authentication. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +token: VAULT_TOKEN +{{< /code >}} +{{< code json >}} +{ + "token": "VAULT_TOKEN" +} +{{< /code >}} +{{< /language-toggle >}} + +version | +-------------|------ +description | HashiCorp Vault [key/value store version][14]. +required | true +type | String +allowed values | `v1` and `v2` +example | {{< language-toggle >}} +{{< code yml >}} +version: v1 +{{< /code >}} +{{< code json >}} +{ + "version": "v1" +} +{{< /code >}} +{{< /language-toggle >}} + +##### Rate limiter attributes + +burst | +-------------|------ +description | Maximum amount of burst allowed in a rate interval for the [enterprise/secrets/v1][2] API endpoint. +required | false +type | Integer +example | {{< language-toggle >}} +{{< code yml >}} +burst: 100 +{{< /code >}} +{{< code json >}} +{ + "burst": 100 +} +{{< /code >}} +{{< /language-toggle >}} + +limit | +-------------|------ +description | Maximum number of secrets requests per second that can be transmitted to the backend with the [enterprise/secrets/v1][2] API endpoint. +required | false +type | Float +example | {{< language-toggle >}} +{{< code yml >}} +limit: 10.0 +{{< /code >}} +{{< code json >}} +{ + "limit": 10.0 +} +{{< /code >}} +{{< /language-toggle >}} + + +[1]: ../../../commercial/ +[2]: ../../../api/enterprise/secrets/ +[3]: ../../../sensuctl/ +[4]: ../../../observability-pipeline/observe-schedule/backend/#environment-variables +[5]: https://www.vaultproject.io/docs/what-is-vault/ +[6]: ../../control-access/rbac#default-users +[7]: ../../../sensuctl/create-manage-resources/#create-resources +[8]: #vaultprovider-spec-attributes +[9]: ../secrets/ +[10]: https://www.vaultproject.io/docs/auth/token/ +[11]: https://www.vaultproject.io/api/other/auth/cert/index.html +[12]: #vaultprovider-client-attributes +[13]: ../../deploy-sensu/secure-sensu/#optional-configure-sensu-agent-mtls-authentication +[14]: https://www.vaultproject.io/docs/secrets/kv +[15]: https://www.vaultproject.io/api/other/auth/cert/index.html#parameters-7 +[16]: ../secrets-management/ +[17]: #rate-limiter-attributes +[18]: https://www.conjur.org/ +[19]: #cyberarkprovider-spec-attributes +[20]: #cyberarkprovider-client-attributes diff --git a/content/sensu-go/6.12/operations/manage-secrets/secrets.md b/content/sensu-go/6.12/operations/manage-secrets/secrets.md new file mode 100644 index 0000000000..72071407da --- /dev/null +++ b/content/sensu-go/6.12/operations/manage-secrets/secrets.md @@ -0,0 +1,383 @@ +--- +title: "Secrets reference" +linkTitle: "Secrets Reference" +reference_title: "Secrets" +type: "reference" +description: "Read this reference to use Sensu's secrets management feature to avoid exposing sensitive information in your Sensu configuration." +weight: 20 +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: manage-secrets +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access the Secret datatype in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} + +Sensu's secrets management eliminates the need to expose secrets in your Sensu configuration. +When a Sensu resource definition requires a secret (for example, a username or password), Sensu allows you to obtain secrets from one or more external secrets providers, so you can both refer to external secrets and consume secrets via [backend environment variables][5]. + +{{% notice note %}} +**NOTE**: Secrets management is implemented for [checks](../../../observability-pipeline/observe-schedule/checks/#check-example-that-uses-secrets-management), [handlers](../../../observability-pipeline/observe-process/handlers/#use-secrets-management-in-a-handler), and [mutators](../../../observability-pipeline/observe-transform/mutators/#use-secrets-management-in-a-mutator). +{{% /notice %}} + +Only Sensu backends have access to request secrets from a [secrets provider][7]. +Sensu backends cache fetched secrets in memory, with no persistence to a Sensu datastore or file on disk. +Secrets provided via a "lease" with a "lease duration" are deleted from Sensu's in-memory cache after the configured number of seconds, prompting the Sensu backend to request the secret again. + +Secrets are only transmitted over a transport layer security (TLS) WebSocket connection. +Unencrypted connections must not transmit privileged information. +For checks, hooks, and dynamic runtime assets, you must [enable mutual TLS (mTLS)][13]. +Sensu will not transmit secrets to agents that do not use mTLS. + +Sensu only exposes secrets to Sensu services like environment variables and automatically redacts secrets from all logs, the API, and the web UI. + +## Secret examples + +A secret resource definition refers to a secrets `id` and a secrets `provider`. +Read the [secrets provider reference][7] for the provider specification. + +### Env provider example + +This example shows a resource definition for a secret that uses Sensu's `Env` secrets provider: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Secret +api_version: secrets/v1 +metadata: + name: sensu-ansible-token +spec: + id: ANSIBLE_TOKEN + provider: env +{{< /code >}} + +{{< code json >}} +{ + "type": "Secret", + "api_version": "secrets/v1", + "metadata": { + "name": "sensu-ansible-token" + }, + "spec": { + "id": "ANSIBLE_TOKEN", + "provider": "env" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +### CyberArk Conjur example + +Configure secrets that target CyberArk Conjur as shown in the following example: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Secret +api_version: secrets/v1 +metadata: + name: sensu-ansible +spec: + id: Sensu/ansibleToken + provider: cyberark +{{< /code >}} + +{{< code json >}} +{ + "type": "Secret", + "api_version": "secrets/v1", + "metadata": { + "name": "sensu-ansible" + }, + "spec": { + "id": "Sensu/ansibleToken", + "provider": "cyberark" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +The `id` value for secrets that target CyberArk Conjur includes the id and variable values specified in the Conjur policy. + +### HashiCorp Vault example + +Configure secrets that target HashiCorp Vault as shown in the following example: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Secret +api_version: secrets/v1 +metadata: + name: sensu-ansible +spec: + id: 'secret/database#password' + provider: vault +{{< /code >}} + +{{< code json >}} +{ + "type": "Secret", + "api_version": "secrets/v1", + "metadata": { + "name": "sensu-ansible" + }, + "spec": { + "id": "secret/database#password", + "provider": "vault" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +The `id` value for secrets that target a HashiCorp Vault must start with the name of the secret's path in Vault. +The [Vault dev server][10] is preconfigured with the secret keyspace already set up. +This is convenient for learning and getting started with Vault secrets management, so this example and our guide to [secrets management][11] use the `secret/` path for the `id` value. +In this example, the name of the secret is `database`. +The database secret contains a key called `password,` and its value is the password to our database. + +## Secret configuration + +You can use the [enterprise/secrets/v1 API endpoints][2] and [sensuctl][3] to create, view, and manage your secrets configuration. +To manage secrets configuration with sensuctl, configure sensuctl as the default [`admin` user][6]. + +The [standard sensuctl subcommands][4] are available for secrets (list, info, and delete). + +To list all secrets: + +{{< code shell >}} +sensuctl secret list +{{< /code >}} + +To review a secret's status: + +{{< code shell >}} +sensuctl secret info SECRET_NAME +{{< /code >}} + +To delete a secret: + +{{< code shell >}} +sensuctl secret delete SECRET_NAME +{{< /code >}} + +`SECRET_NAME` is the value specified in the secret's `name` [metadata attribute][12]. + +## Secret specification + +### Top-level attributes + +api_version | +-------------|------ +description | Top-level attribute that specifies the Sensu API group and version. For secrets configuration in this version of Sensu, the api_version should always be `secrets/v1`. +required | Required for secrets configuration in `wrapped-json` or `yaml` format. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +api_version: secrets/v1 +{{< /code >}} +{{< code json >}} +{ + "api_version": "secrets/v1" +} +{{< /code >}} +{{< /language-toggle >}} + +metadata | | +-------------|------ +description | Top-level scope that contains the secret's `name` and `namespace` as well as the `created_by` field. +required | true +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +metadata: + name: sensu-ansible-token + namespace: default + created_by: admin +{{< /code >}} +{{< code json >}} +{ + "metadata": { + "name": "sensu-ansible-token", + "namespace": "default", + "created_by": "admin" + } +} +{{< /code >}} +{{< /language-toggle >}} + +spec | +-------------|------ +description | Top-level map that includes secrets configuration [spec attributes][8]. +required | Required for secrets configuration in `wrapped-json` or `yaml` format. +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +spec: + id: ANSIBLE_TOKEN + provider: env +{{< /code >}} +{{< code json >}} +{ + "spec": { + "id": "ANSIBLE_TOKEN", + "provider": "env" + } +} +{{< /code >}} +{{< /language-toggle >}} + +type | +-------------|------ +description | Top-level attribute that specifies the resource type. For secrets configuration, the type should always be `Secret`. +required | Required for secrets configuration in `wrapped-json` or `yaml` format. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +type: Secret +{{< /code >}} +{{< code json >}} +{ + "type": "Secret" +} +{{< /code >}} +{{< /language-toggle >}} + +### Metadata attributes + +| created_by | | +-------------|------ +description | Username of the Sensu user who created the secret or last updated the secret. Sensu automatically populates the `created_by` field when the secret is created or updated. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +created_by: admin +{{< /code >}} +{{< code json >}} +{ + "created_by": "admin" +} +{{< /code >}} +{{< /language-toggle >}} + +name | | +-------------|------ +description | Name for the secret that is used internally by Sensu. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +name: sensu-ansible-token +{{< /code >}} +{{< code json >}} +{ + "name": "sensu-ansible-token" +} +{{< /code >}} +{{< /language-toggle >}} + +namespace | | +-------------|------ +description | [Sensu RBAC namespace][9] that the secret belongs to. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +namespace: default +{{< /code >}} +{{< code json >}} +{ + "namespace": "default" +} +{{< /code >}} +{{< /language-toggle >}} + +### Spec attributes + +id | +-------------|------ +description | Identifying key for the provider to use to retrieve the secret.

    For the Env secrets provider, the id is the environment variable name.

    For the CyberArkProvider secrets provider, the id specifies the policy id and variable values.

    For the VaultProvider secrets provider, the id specifies the secrets engine path, the path to the secret within that secrets engine, and the field to retrieve within the secret. +required | true +type | String +example for Env | {{< language-toggle >}} +{{< code yml >}} +id: ANSIBLE_TOKEN +{{< /code >}} +{{< code json >}} +{ + "id": "ANSIBLE_TOKEN" +} +{{< /code >}} +{{< /language-toggle >}} +example for CyberArk Conjur | {{< language-toggle >}} +{{< code yml >}} +id: Sensu/ansibleToken +{{< /code >}} +{{< code json >}} +{ + "id": "Sensu/ansibleToken" +} +{{< /code >}} +{{< /language-toggle >}} +example for Vault KV Secrets Engine v1 | {{< language-toggle >}} +{{< code yml >}} +id: secret/ansible#token +{{< /code >}} +{{< code json >}} +{ + "id": "secret/ansible#token" +} +{{< /code >}} +{{< /language-toggle >}} +example for Vault KV Secrets Engine v2 | {{< language-toggle >}} +{{< code yml >}} +id: secrets/sensu#ansible#token +{{< /code >}} +{{< code json >}} +{ + "id": "secrets/sensu#ansible#token" +} +{{< /code >}} +{{< /language-toggle >}} + +provider | +-------------|------ +description | Name of the provider with the secret. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +provider: vault +{{< /code >}} +{{< code json >}} +{ + "provider": "vault" +} +{{< /code >}} +{{< /language-toggle >}} + + +[2]: ../../../api/enterprise/secrets/ +[3]: ../../../sensuctl/ +[4]: ../../../sensuctl/create-manage-resources/#subcommands +[5]: ../../../observability-pipeline/observe-schedule/backend/#environment-variables +[6]: ../../control-access/rbac#default-users +[7]: ../secrets-providers/ +[8]: #spec-attributes +[9]: ../../control-access/namespaces/ +[10]: https://learn.hashicorp.com/vault/getting-started/dev-server +[11]: ../secrets-management/ +[12]: #metadata-attributes +[13]: ../../deploy-sensu/secure-sensu/#optional-configure-sensu-agent-mtls-authentication diff --git a/content/sensu-go/6.12/operations/monitor-sensu/_index.md b/content/sensu-go/6.12/operations/monitor-sensu/_index.md new file mode 100644 index 0000000000..e02dd21717 --- /dev/null +++ b/content/sensu-go/6.12/operations/monitor-sensu/_index.md @@ -0,0 +1,37 @@ +--- +title: "Monitor Sensu" +description: "Log Sensu services and monitor your Sensu backend with another Sensu backend to maintain visibility into your observability workflows." +product: "Sensu Go" +version: "6.12" +weight: 40 +layout: "single" +toc: true +menu: + sensu-go-6.12: + parent: operations + identifier: monitor-sensu +--- + +Use the guides and references in the Monitor Sensu category to successfully monitor your Sensu installation. + +## Log Sensu services and monitor with Sensu + +Learn how to [log Sensu services with systemd][1], including adding log forwarding from journald to syslog, using rsyslog to write logging data to disk, and setting up log rotation. + +Read [Monitor Sensu with Sensu][2] to monitor the Sensu backend with another Sensu backend or cluster: use a secondary Sensu instance to notify you when your primary Sensu instance is down (and vice versa). + +## Retrieve cluster health data + +The [health reference][3] explains how to use Sensu’s /health API to ensure your backend is up and running and check the health of your etcd cluster members and PostgreSQL datastore resources. +Learn how to read the JSON response for /health API requests by reviewing examples of responses for clusters with healthy and unhealthy members and the response specification. + +## Learn about Tessen + +The [Tessen reference][4] explains the Sensu call-home service, which is enabled by default on Sensu backends and required for licensed Sensu instances. +We rely on anonymized Tessen data to understand how Sensu is being used and make informed decisions about product improvements. + + +[1]: log-sensu-systemd/ +[2]: monitor-sensu-with-sensu/ +[3]: health/ +[4]: tessen/ diff --git a/content/sensu-go/6.12/operations/monitor-sensu/health.md b/content/sensu-go/6.12/operations/monitor-sensu/health.md new file mode 100644 index 0000000000..723ae6f793 --- /dev/null +++ b/content/sensu-go/6.12/operations/monitor-sensu/health.md @@ -0,0 +1,283 @@ +--- +title: "Health reference" +linkTitle: "Health Reference" +reference_title: "Health" +type: "reference" +description: "Access health data for your Sensu instance. Read this page to learn about the health information you can retrieve." +weight: 30 +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: monitor-sensu +--- + +Use Sensu's [/health API][1] to make sure your backend is up and running and check the health of your etcd cluster members and [PostgreSQL datastore resources][2]. + +A request to the /health API endpoint retrieves a JSON map with health data for your Sensu instance. +Here's an example request to the health endpoint: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/health +{{< /code >}} + +## Healthy cluster example + +In this example, all cluster members are healthy. + +{{< code text >}} +{ + "Alarms": null, + "ClusterHealth": [ + { + "MemberID": 9861478486968594000, + "MemberIDHex": "88db026f7feb72b4", + "Name": "backend01", + "Err": "", + "Healthy": true + }, + { + "MemberID": 16828500076473182000, + "MemberIDHex": "e98ad7a888d16bd6", + "Name": "backend02", + "Err": "", + "Healthy": true + }, + { + "MemberID": 848052855499371400, + "MemberIDHex": "bc4e39432cbb36d", + "Name": "backend03", + "Err": "", + "Healthy": true + } + ], + "Header": { + "cluster_id": 17701109828877156000, + "member_id": 16828500076473182000, + "raft_term": 42 + } +}, + "PostgresHealth": [ + { + "Name": "my-first-postgres", + "Active": true, + "Healthy": true + }, + { + "Name": "my-other-postgres", + "Active": false, + "Healthy": false + } + ] +} +{{< /code >}} + +## Unhealthy cluster member example + +In this example, one cluster member is unhealthy: it cannot communicate with the other cluster members. + +{{< code text >}} +{ + "Alarms": null, + "ClusterHealth": [ + { + "MemberID": 9861478486968594000, + "MemberIDHex": "88db026f7feb72b4", + "Name": "backend01", + "Err": "context deadline exceeded", + "Healthy": false + }, + { + "MemberID": 16828500076473182000, + "MemberIDHex": "e98ad7a888d16bd6", + "Name": "backend02", + "Err": "", + "Healthy": true + }, + { + "MemberID": 848052855499371400, + "MemberIDHex": "bc4e39432cbb36d", + "Name": "backend03", + "Err": "", + "Healthy": true + } + ], + "Header": { + "cluster_id": 17701109828877156000, + "member_id": 16828500076473182000, + "raft_term": 42 + } +}, + "PostgresHealth": [ + { + "Name": "my-first-postgres", + "Active": true, + "Healthy": true + }, + { + "Name": "my-other-postgres", + "Active": false, + "Healthy": false + } + ] +} +{{< /code >}} + +{{% notice note %}} +**NOTE**: The HTTP response codes for the health endpoint indicate whether your request reached Sensu rather than the health of your Sensu instance. +In this example, even though the cluster is unhealthy, the request itself reached Sensu, so the response code is `200 OK`. +To determine the health of your Sensu instance, you must process the JSON response body. +The [health specification](#health-specification) describes each attribute in the response body. +{{% /notice %}} + +## Health specification + +### Top-level attributes + +Alarms | +-------------|------ +description | Top-level attribute that lists all active etcd alarms. +required | true +type | String +example | {{< code shell >}}"Alarms": null{{< /code >}} + +ClusterHealth | +--------------|------ +description | Top-level attribute that includes health status information for every etcd cluster member. +required | true +type | Map of key-value pairs +example | {{< code shell >}} +"ClusterHealth": [ + { + "MemberID": 2882886652148554927, + "MemberIDHex": "8923110df66458af", + "Name": "default", + "Err": "", + "Healthy": true + } + ]{{< /code >}} + +Header | +-------------|------ +description | Top-level map that includes the response header for the entire cluster response. +required | true +type | Map of key-value pairs +example | {{< code shell >}} +"Header": { + "cluster_id": 4255616344056076734, + "member_id": 2882886652148554927, + "raft_term": 26 + } +{{< /code >}} + +PostgresHealth | +---------------|------ +description | Top-level map that includes health information for PostgreSQL resources. If your Sensu instance is not configured to use a [PostgreSQL datastore][2], the health payload will not include `PostgresHealth`. +type | Map of key-value pairs +example | {{< code shell >}} +"PostgresHealth": [ + { + "Name": "postgres-test", + "Active": false, + "Healthy": false + }, + { + "Name": "postgres", + "Active": true, + "Healthy": true + } + ] +{{< /code >}} + +#### ClusterHealth attributes + +Err | +-------------|------ +description | Any errors Sensu encountered while checking the etcd cluster member's health. +required | true +type | String +example | {{< code shell >}}"Err": ""{{< /code >}} + +Healthy | +-------------|------ +description | `true` if the etcd cluster member is connected. Otherwise, `false`. +required | true +type | Boolean +default | `false` +example | {{< code shell >}}"Healthy": true{{< /code >}} + +MemberID | +-------------|------ +description | The etcd cluster member's ID. +required | true +type | Integer +example | {{< code shell >}}"MemberID": 2882886652148554927{{< /code >}} + +MemberIDHex | +-------------|------ +description | The hexadecimal representation of the etcd cluster member's ID. +required | true +type | String +example | {{< code shell >}}"MemberIDHex": "8923110df66458af"{{< /code >}} + +Name | +-------------|------ +description | The etcd cluster member's name. +required | true +type | String +example | {{< code shell >}}"Name": "default"{{< /code >}} + +#### Header attributes + +cluster_id | +-------------|------ +description | The etcd cluster ID. +required | true +type | Integer +example | {{< code shell >}}"cluster_id": 4255616344056076734{{< /code >}} + +member_id | +-------------|------ +description | The etcd cluster member's ID. +required | true +type | Integer +example | {{< code shell >}}"member_id": 2882886652148554927{{< /code >}} + +raft_term | +-------------|------ +description | The etcd cluster member's [raft term][4]. +required | true +type | Integer +example | {{< code shell >}}"raft_term": 26{{< /code >}} + +#### PostgresHealth attributes + +Active | +-------------|------ +description | `true` if the datastore is configured to use the PostgreSQL configuration. Otherwise, `false`. +required | true +type | Boolean +default | `false` +example | {{< code shell >}}"Active": true{{< /code >}} + +Healthy | +-------------|------ +description | `true` if the PostgreSQL datastore is connected and can query the events table. Otherwise, `false`. +required | true +type | Boolean +default | `false` +example | {{< code shell >}}"Healthy": true{{< /code >}} + +Name | +-------------|------ +description | The PostgreSQL configuration resource. Sensu retrieves the `Name` from [datastore metadata][3]. +required | true +type | String +example | {{< code shell >}}"Name": "postgres"{{< /code >}} + + +[1]: ../../../api/other/health/ +[2]: ../../deploy-sensu/datastore/#scale-event-storage +[3]: ../../deploy-sensu/datastore/#metadata-attributes +[4]: https://etcd.io/docs/latest/learning/api/#response-header diff --git a/content/sensu-go/6.12/operations/monitor-sensu/log-sensu-systemd.md b/content/sensu-go/6.12/operations/monitor-sensu/log-sensu-systemd.md new file mode 100644 index 0000000000..dd99213638 --- /dev/null +++ b/content/sensu-go/6.12/operations/monitor-sensu/log-sensu-systemd.md @@ -0,0 +1,126 @@ +--- +title: "Log Sensu services with systemd" +linkTitle: "Log Sensu Services" +guide_title: "Log Sensu services with systemd" +type: "guide" +description: "Add Sensu log forwarding from journald to syslog, have rsyslog write logging data to disk, and set up log rotation of the newly created log files." +weight: 10 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: monitor-sensu +--- + +By default, systems where systemd is the service manager do not write logs to `/var/log/sensu/` for the `sensu-agent` and the `sensu-backend` services. +This guide explains how to add log forwarding from journald to syslog, have rsyslog write logging data to disk, and set up log rotation of the newly created log files. + +## Requirements + +To follow this guide, install the Sensu [backend][2] and make sure at least one Sensu [agent][3] is running. + +## Configure journald + +To configure journald to forward logging data to syslog, modify `/etc/systemd/journald.conf` to include the following line: + +{{< code shell >}} +ForwardToSyslog=yes +{{< /code >}} + +## Configure rsyslog + +Set up rsyslog to write the logging data received from journald to `/var/log/sensu/servicename.log`. +In this example, the `sensu-backend` and `sensu-agent` logging data is sent to individual files named after the service. +The `sensu-backend` is not required if you're only setting up log forwarding for the `sensu-agent` service. + +{{% notice note %}} +**NOTE**: Use a `conf` file name that will ensure the file is loaded before the default file in `/etc/rsyslog.d/`, which uses 50. +This example uses `40-sensu-backend.conf` and `40-sensu-agent.conf` for this reason. +{{% /notice %}} + +1. For the sensu-backend service, in /etc/rsyslog.d/40-sensu-backend.conf, add: +{{< code shell >}} +if $programname == 'sensu-backend' then { + /var/log/sensu/sensu-backend.log + & stop +} +{{< /code >}} + +2. For the sensu-agent service, in /etc/rsyslog.d/40-sensu-agent.conf, add: +{{< code shell >}} +if $programname == 'sensu-agent' then { + /var/log/sensu/sensu-agent.log + & stop +} +{{< /code >}} + +3. **On Ubuntu systems**, run `chown -R syslog:adm /var/log/sensu` so syslog can write to that directory. + +4. Restart journald: +{{< code shell >}} +systemctl restart systemd-journald +{{< /code >}} + +5. Restart rsyslog to apply the new configuration: +{{< code shell >}} +systemctl restart rsyslog +{{< /code >}} + +{{% notice note %}} +**NOTE**: Sensu log messages include the Sensu [log level](../../maintain-sensu/troubleshoot/#log-levels) as part of the log data. +Users with rsyslog expertise may be able to extract the log level from Sensu log messages and use rsyslog processing capabilities to separate the log messages into different files based on log level. +{{% /notice %}} + +## Set up log rotation + +Set up log rotation for newly created log files to ensure logging does not fill up your disk. + +These examples rotate the log files `/var/log/sensu/sensu-agent.log` and `/var/log/sensu/sensu-backend.log` weekly, unless the size of 100M is reached first. +The last seven rotated logs are kept and compressed, with the exception of the most recent log. +After rotation, `rsyslog` is restarted to ensure logging is written to a new file and not the most recent rotated file. + +1. In /etc/logrotate.d/sensu-agent.conf, add: +{{< code shell >}} +/var/log/sensu/sensu-agent.log { + daily + rotate 7 + size 100M + compress + delaycompress + postrotate + /bin/systemctl restart rsyslog + endscript +} +{{< /code >}} + +2. In /etc/logrotate.d/sensu-backend.conf, add: +{{< code shell >}} +/var/log/sensu/sensu-backend.log { + daily + rotate 7 + size 100M + compress + delaycompress + postrotate + /bin/systemctl restart rsyslog + endscript +} +{{< /code >}} + +Use the following command to find out what logrotate would do if it were executed now based on the above schedule and size threshold. +The `-d` flag will output details, but it will not take action on the logs or execute the postrotate script: + +{{< code shell >}} +logrotate -d /etc/logrotate.d/sensu.conf +{{< /code >}} + +## What's next + +Sensu also offers observability event data logging to a separate JSON log file. +Read the [backend reference][1] for more information about event logging. + + +[1]: ../../../observability-pipeline/observe-schedule/backend/#event-logging +[2]: ../../deploy-sensu/install-sensu/#install-the-sensu-backend +[3]: ../../deploy-sensu/install-sensu/#install-sensu-agents diff --git a/content/sensu-go/6.12/operations/monitor-sensu/monitor-sensu-with-sensu.md b/content/sensu-go/6.12/operations/monitor-sensu/monitor-sensu-with-sensu.md new file mode 100644 index 0000000000..41b06b4cb8 --- /dev/null +++ b/content/sensu-go/6.12/operations/monitor-sensu/monitor-sensu-with-sensu.md @@ -0,0 +1,514 @@ +--- +title: "Monitor Sensu with Sensu" +linkTitle: "Monitor Sensu with Sensu" +guide_title: "Monitor Sensu with Sensu" +type: "guide" +description: "Make sure your Sensu components are properly monitored. This guide describes best practices and strategies for monitoring Sensu." +weight: 20 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: monitor-sensu +--- + +This guide describes best practices and strategies for monitoring the Sensu backend with another Sensu backend or cluster. + +To completely monitor Sensu (a Sensu backend with internal etcd and an agent), you will need at least one independent Sensu instance in addition to the primary instance you want to monitor. +The second Sensu instance will ensure that you are notified when the primary is down and vice versa. + +This guide requires Sensu plugins using dynamic runtime assets. +For more information about using Sensu plugins, read [Use dynamic runtime assets to install plugins][1]. + +{{% notice note %}} +**NOTE**: Although this guide describes approaches for monitoring a single backend, these strategies are also useful for monitoring individual members of a backend cluster.

    +This guide does not describe Sensu agent [keepalive monitoring](../../../observability-pipeline/observe-schedule/agent/#keepalive-monitoring). +{{% /notice %}} + +The checks in this guide monitor the following ports and endpoints: + +| Port | Endpoint | Description | +|------|----------|-------------| +| 2379 | `/health` | Etcd health endpoint. Provides health status for etcd nodes. | +| 8080 | `/health` | Sensu Go health endpoint. Provides health status for Sensu backends, as well as for PostgreSQL (when enabled). | + +## Requirements + +To follow this guide, install the Sensu [backend][10], make sure at least one Sensu [agent][11] is running, and configure [sensuctl][12] to connect to the backend as the [`admin` user][13]. + +## Register dynamic runtime asset + +To power the checks to monitor your Sensu backend, external etcd, and PostgreSQL instances, add the sensu/http-checks dynamic runtime asset. +This asset includes the `http-json` plugin, which your checks will rely on. + +To register the sensu/http-checks dynamic runtime asset, run: + +{{< code shell >}} +sensuctl asset add sensu/http-checks:0.5.0 -r http-checks +{{< /code >}} + +The response will confirm that the asset was added: + +{{< code text >}} +fetching bonsai asset: sensu/http-checks:0.5.0 +added asset: sensu/http-checks:0.5.0 + +You have successfully added the Sensu asset resource, but the asset will not get downloaded until +it's invoked by another Sensu resource (ex. check). To add this runtime asset to the appropriate +resource, populate the "runtime_assets" field with ["http-checks"]. +{{< /code >}} + +This example uses the `-r` (rename) flag to specify a shorter name for the dynamic runtime asset: http-checks. + +To confirm that the asset is ready to use, run: + +{{< code shell >}} +sensuctl asset list +{{< /code >}} + +The response should list the renamed http-checks dynamic runtime asset: + +{{< code text >}} + Name URL Hash +────────────── ───────────────────────────────────────────────────────────────────── ────────── + http-checks //assets.bonsai.sensu.io/.../http-checks_0.5.0_linux_armv7.tar.gz b28f8c3 + http-checks //assets.bonsai.sensu.io/.../http-checks_0.5.0_linux_arm64.tar.gz 7308f9c + http-checks //assets.bonsai.sensu.io/.../http-checks_0.5.0_linux_386.tar.gz 6457583 + http-checks //assets.bonsai.sensu.io/.../http-checks_0.5.0_windows_amd64.tar.gz b936ca0 + http-checks //assets.bonsai.sensu.io/.../http-checks_0.5.0_darwin_amd64.tar.gz 38e6cb8 + http-checks //assets.bonsai.sensu.io/.../http-checks_0.5.0_linux_amd64.tar.gz bc5fc3b +{{< /code >}} + +Because plugins are published for multiple platforms, including Linux and Windows, the output will include multiple entries for each of the dynamic runtime assets. + +{{% notice note %}} +**NOTE**: Sensu does not download and install dynamic runtime asset builds onto the system until they are needed for command execution. +{{% /notice %}} + +## Monitor your Sensu backend instances + +Monitor the host running the `sensu-backend` *locally* by a `sensu-agent` process for operating system checks and metrics. + +For Sensu components that must be running for Sensu to create events, you should also monitor the `sensu-backend` remotely from an independent Sensu instance. +This will allow you to monitor whether your Sensu event pipeline is working. + +To do this, add checks that use the `http-json` plugin from the sensu/http-checks dynamic runtime asset to query Sensu's /health API for your primary (Backend Alpha) and secondary (Backend Beta) backends. + +{{% notice note %}} +**NOTE**: These examples use the sensu/http-checks dynamic runtime asset. +Follow the instructions above to [register sensu/http-checks](#register-dynamic-runtime-asset) if you have not previously registered it. +{{% /notice %}} + +{{< language-toggle >}} + +{{< code yml "YML - Backend Alpha">}} +cat << EOF | sensuctl create +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: check_beta_backend_health +spec: + command: http-json --url http://sensu-backend-beta:8080/health --query ".ClusterHealth.[0].Healthy" --expression "== true" + subscriptions: + - backend_alpha + interval: 10 + publish: true + timeout: 10 + runtime_assets: + - http-checks +EOF +{{< /code >}} + +{{< code yml "YML - Backend Beta">}} +cat << EOF | sensuctl create +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: check_alpha_backend_health +spec: + command: http-json --url http://sensu-backend-alpha:8080/health --query ".ClusterHealth.[0].Healthy" --expression "== true" + subscriptions: + - backend_beta + interval: 10 + publish: true + timeout: 10 + runtime_assets: + - http-checks +EOF +{{< /code >}} + +{{< code json "JSON - Backend Alpha">}} +cat << EOF | sensuctl create +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "check_beta_backend_health" + }, + "spec": { + "command": "http-json --url http://sensu-backend-beta:8080/health --query \".ClusterHealth.[0].Healthy\" --expression \"== true\"", + "subscriptions": [ + "backend_alpha" + ], + "interval": 10, + "publish": true, + "timeout": 10, + "runtime_assets": [ + "http-checks" + ] + } +} +EOF +{{< /code >}} + +{{< code json "JSON - Backend Beta">}} +cat << EOF | sensuctl create +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "check_alpha_backend_health" + }, + "spec": { + "command": "http-json --url http://sensu-backend-alpha:8080/health --query \".ClusterHealth.[0].Healthy\" --expression \"== true\"", + "subscriptions": [ + "backend_beta" + ], + "interval": 10, + "publish": true, + "timeout": 10, + "runtime_assets": [ + "http-checks" + ] + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + +A successful health check result will be similar to this example: + +{{< code text >}} +http-json OK: The value true found at .ClusterHealth.[0].Healthy matched with expression "== true" and returned true +{{< /code >}} + +## Monitor external etcd + +If your Sensu Go deployment uses an external etcd cluster, you'll need to check the health of the respective etcd instances for your primary (Backend Alpha) and secondary (Backend Beta) backends. + +{{% notice note %}} +**NOTE**: These examples use the sensu/http-checks dynamic runtime asset. +Follow the instructions above to [register sensu/http-checks](#register-dynamic-runtime-asset) if you have not previously registered it. +{{% /notice %}} + +{{< language-toggle >}} + +{{< code yml "YML - Backend Alpha">}} +cat << EOF | sensuctl create +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: check_beta_etcd_health +spec: + command: http-json --url http://sensu-etcd-beta:2379/health --query ".ClusterHealth.[0].Healthy" --expression "== true" + subscriptions: + - backend_alpha + interval: 10 + publish: true + timeout: 10 + runtime_assets: + - http-checks +EOF +{{< /code >}} + +{{< code yml "YML - Backend Beta">}} +cat << EOF | sensuctl create +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: check_alpha_etcd_health +spec: + command: http-json --url http://sensu-etcd-alpha:2379/health --query ".ClusterHealth.[0].Healthy" --expression "== true" + subscriptions: + - backend_beta + interval: 10 + publish: true + timeout: 10 + runtime_assets: + - http-checks +EOF +{{< /code >}} + +{{< code json "JSON - Backend Alpha">}} +cat << EOF | sensuctl create +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "check_beta_etcd_health" + }, + "spec": { + "command": "http-json --url http://sensu-etcd-beta:2379/health --query \".ClusterHealth.[0].Healthy\" --expression \"== true\"", + "subscriptions": [ + "backend_alpha" + ], + "interval": 10, + "publish": true, + "timeout": 10, + "runtime_assets": [ + "http-checks" + ] + } +} +EOF +{{< /code >}} + +{{< code json "JSON - Backend Beta">}} +cat << EOF | sensuctl create +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "check_alpha_etcd_health" + }, + "spec": { + "command": "http-json --url http://sensu-etcd-alpha:2379/health --query \".ClusterHealth.[0].Healthy\" --expression \"== true\"", + "subscriptions": [ + "backend_beta" + ], + "interval": 10, + "publish": true, + "timeout": 10, + "runtime_assets": [ + "http-checks" + ] + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + +A successful health check result will be similar to this example: + +{{< code text >}} +http-json OK: The value true found at .ClusterHealth.[0].Healthy matched with expression "== true" and returned true +{{< /code >}} + +## Monitor PostgreSQL + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access enterprise-scale PostgreSQL event storage in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} + +If you're using PostgreSQL for event storage, we recommend monitoring your PostgreSQL event store's health. + +The connection to PostgreSQL is exposed on Sensu's `/health` endpoint, which provides information about the event store's health. +PostgreSQL data from the `/health` endpoint will look like this example: + +{{< code text >}} +{ + "Alarms": null, + "ClusterHealth": [ + { + "MemberID": 3470366781180380700, + "MemberIDHex": "302938336092857e", + "Name": "sensu00", + "Err": "", + "Healthy": true + }, + { + "MemberID": 15883454222313069000, + "MemberIDHex": "dc6d5d7607261af7", + "Name": "sensu01", + "Err": "", + "Healthy": true + }, + { + "MemberID": 11377294497886210000, + "MemberIDHex": "9de44510fb838bbd", + "Name": "sensu02", + "Err": "", + "Healthy": true + } + ], + "Header": { + "cluster_id": 13239446193995635000, + "member_id": 3470366781180380700, + "raft_term": 1549 + }, + "PostgresHealth": [ + { + "Name": "sensu_postgres", + "Active": true, + "Healthy": true + } + ] +} +{{< /code >}} + +To monitor PostgreSQL's health from Sensu, create checks that use the `http-json` plugin from the sensu/http-checks dynamic runtime asset. + +{{% notice note %}} +**NOTE**: These examples use the sensu/http-checks dynamic runtime asset. +Follow the instructions above to [register sensu/http-checks](#register-dynamic-runtime-asset) if you have not previously registered it. +{{% /notice %}} + +After you register the sensu/http-checks dynamic runtime asset, create two checks ("healthy" and "active") to monitor PostgreSQL's health from Sensu. +Make sure to update the `--url` value with your backend address before running the commands to create the checks. + +Run the following command to add the "healthy" check: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +cat << EOF | sensuctl create +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: postgres_healthy_http_check +spec: + command: http-json --url https://sensu.example.com:8080/health --query ".PostgresHealth.[0].Healthy" --expression "== true" + round_robin: true + publish: true + interval: 60 + subscriptions: + - system + runtime_assets: + - http-checks +EOF +{{< /code >}} + +{{< code shell "JSON" >}} +cat << EOF | sensuctl create +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "postgres_healthy_http_check" + }, + "spec": { + "command": "http-json --url https://sensu.example.com:8080/health --query \".PostgresHealth.[0].Healthy\" --expression \"== true\"", + "round_robin": true, + "publish": true, + "interval": 60, + "subscriptions": [ + "system" + ], + "runtime_assets": [ + "http-checks" + ] + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + +Run the following command to add the "active" check: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +cat << EOF | sensuctl create +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: postgres_active_http_check +spec: + command: http-json --url https://sensu.example.com:8080/health --query ".PostgresHealth.[0].Active" --expression "== true" + round_robin: true + publish: true + interval: 60 + subscriptions: + - system + runtime_assets: + - http-checks +EOF +{{< /code >}} + +{{< code shell "JSON" >}} +cat << EOF | sensuctl create +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "postgres_active_http_check" + }, + "spec": { + "command": "http-json --url https://sensu.example.com:8080/health --query \".PostgresHealth.[0].Active\" --expression \"== true\"", + "round_robin": true, + "publish": true, + "interval": 60, + "subscriptions": [ + "system" + ], + "runtime_assets": [ + "http-checks" + ] + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + +Successful PostgreSQL health check results will be similar to this example: + +{{< code text >}} +http-json OK: The value true found at .PostgresHealth.[0].Healthy matched with expression "== true" and returned true +http-json OK: The value true found at .PostgresHealth.[0].Active matched with expression "== true" and returned true +{{< /code >}} + +In the Sensu web UI, you should see check results similar to these examples: + +{{< figure src="/images/go/monitor_sensu_with_sensu/postgres_health_http_check.png" alt="Screenshot of Sensu Web UI shows a passing PostgreSQL health check" link="/images/go/monitor_sensu_with_sensu/postgres_health_http_check.png" target="_blank" >}} + +{{< figure src="/images/go/monitor_sensu_with_sensu/postgres_active_http_check.png" alt="Screenshot of Sensu Web UI shows a passing PostgreSQL active check" link="/images/go/monitor_sensu_with_sensu/postgres_active_http_check.png" target="_blank" >}} + +## What's next + +To receive alerts based on your backend health checks, configure a [pipeline][6] with [event filters][3] and a [handler][7] and update your check definitions to reference the pipeline in the [pipelines attribute][8]. + +Follow any of these guides to learn how to configure event filters, handlers, and pipelines and start sending alerts based on event data: + +* [Send email alerts with a pipeline][14] +* [Send PagerDuty alerts with Sensu][15] +* [Send Slack alerts with a pipeline][16] + +Read more about the Sensu features you used in this guide: + +- [Dynamic runtime assets][18] and [sensu/http-checks][5] +- [sensuctl][17] +- [/health API][2] +- [PostgreSQL enterprise datastore][4] +- [Web UI][9] + + +[1]: ../../../plugins/use-assets-to-install-plugins/ +[2]: ../../../api/other/health/ +[3]: ../../../observability-pipeline/observe-filter/filters/ +[4]: ../../deploy-sensu/scale-event-storage/ +[5]: https://bonsai.sensu.io/assets/sensu/http-checks +[6]: ../../../observability-pipeline/observe-process/pipelines/ +[7]: ../../../observability-pipeline/observe-process/handlers/ +[8]: ../../../observability-pipeline/observe-schedule/checks/#pipelines-attribute +[9]: ../../../web-ui/ +[10]: ../../../operations/deploy-sensu/install-sensu/#install-the-sensu-backend +[11]: ../../../operations/deploy-sensu/install-sensu/#install-sensuctl +[12]: ../../../operations/deploy-sensu/install-sensu/#install-sensu-agents +[13]: ../../../operations/control-access/rbac/#default-users +[14]: ../../../observability-pipeline/observe-process/send-email-alerts/ +[15]: ../../../observability-pipeline/observe-process/send-pagerduty-alerts/ +[16]: ../../../observability-pipeline/observe-process/send-slack-alerts/ +[17]: ../../../sensuctl/ +[18]: ../../../plugins/assets/ diff --git a/content/sensu-go/6.12/operations/monitor-sensu/ready.md b/content/sensu-go/6.12/operations/monitor-sensu/ready.md new file mode 100644 index 0000000000..dc3f8bb976 --- /dev/null +++ b/content/sensu-go/6.12/operations/monitor-sensu/ready.md @@ -0,0 +1,65 @@ +--- +title: "Ready reference" +linkTitle: "Ready Reference" +reference_title: "Ready" +type: "reference" +description: "Access readiness data for your Sensu instance. Read this page to learn about the readiness information you can retrieve." +weight: 35 +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: monitor-sensu +--- + +Use Sensu's [/ready API endpoint][1] to confirm whether a Sensu instance is ready to serve API requests and accept agent connections. + +A request to the /ready backend API endpoint retrieves a text response with information about whether your Sensu instance is ready to serve API requests. +Here's an example request to the /ready API endpoint: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8080/ready +{{< /code >}} + +A request to the /ready agent transport API endpoint via the backend WebSocket retrieves information about whether your Sensu instance is ready to accept agent connections. +Here's an example request to the /ready agent transport API endpoint using the default WebSocket port 8081: + +{{< code shell >}} +curl -X GET \ +http://127.0.0.1:8081/ready +{{< /code >}} + +## Ready response example + +The following response means that the Sensu instance is ready to serve API requests or accept agent connections: + +{{< code text >}} +ready +{{< /code >}} + +## Not ready response examples + +To help prevent instability during sensu-backend startup, use the [`api-serve-wait-time`][2] and [`agent-serve-wait-time`][3] backend configuration options. + +Use `api-serve-wait-time` to configure a delay after startup before the backend API will serve traffic. +Until the specified duration expires, the text response body will state that the API is unavailable: + +{{< code text >}} +API unavailable during startup. +See api-serve-wait-time settings. +{{< /code >}} + +Use `agent-serve-wait-time` to configure a delay after startup before the agent listener will begin accepting agent connections. +Until the specified duration expires, the text response body will state that agentd is unavailable: + +{{< code text >}} +agentd temporarily unavailable during startup +{{< /code >}} + +Not-ready responses include a `Retry-After` header that lists the specified `api-serve-wait-time` or `agent-serve-wait-time` duration. + + +[1]: ../../../api/other/ready/ +[2]: ../../../observability-pipeline/observe-schedule/backend/#api-serve-wait-time +[3]: ../../../observability-pipeline/observe-schedule/backend/#agent-serve-wait-time diff --git a/content/sensu-go/6.12/operations/monitor-sensu/tessen.md b/content/sensu-go/6.12/operations/monitor-sensu/tessen.md new file mode 100644 index 0000000000..72fedea2ae --- /dev/null +++ b/content/sensu-go/6.12/operations/monitor-sensu/tessen.md @@ -0,0 +1,258 @@ +--- +title: "Tessen reference" +linkTitle: "Tessen Reference" +reference_title: "Tessen" +type: "reference" +description: "Use sensuctl to view and manage your configuration for Tessen, the Sensu call-home service that sends anonymized data about Sensu instances to the Sensu team." +weight: 40 +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: monitor-sensu +--- + +Tessen is the Sensu call-home service. +It is enabled by default on Sensu backends. +Tessen sends anonymized data about Sensu instances to Sensu Inc., including the version, cluster size, number of events processed, and number of resources created (like checks and handlers). +We rely on Tessen data to understand how Sensu is being used and make informed decisions about product improvements. +Read [Announcing Tessen, the Sensu call-home service][1] to learn more about Tessen. + +All data submissions are logged for complete transparency at the `info` log level and transmitted over HTTPS. +Read [Troubleshoot Sensu][5] to set the Sensu backend log level and view logs. + +## Configure Tessen + +You can use [core/v2/tessen][2] and [sensuctl][3] to view your Tessen configuration. +If you are using an unlicensed Sensu instances, you can also use [core/v2/tessen][2] and [sensuctl][3] to opt in or opt out of Tessen. + +{{% notice note %}} +**NOTE**: Tessen is enabled by default on Sensu backends and required for [licensed](../../maintain-sensu/license/) Sensu instances. +If you have a licensed instance and want to opt out of Tessen, contact your account manager. +{{% /notice %}} + +To manage Tessen configuration for your unlicensed instance with sensuctl, configure sensuctl as the default [`admin` user][6]. + +To view Tessen status: + +{{< code shell >}} +sensuctl tessen info +{{< /code >}} + +To opt out of Tessen: + +{{< code shell >}} +sensuctl tessen opt-out +{{< /code >}} + +{{% notice note %}} +**NOTE**: For [licensed](../../maintain-sensu/license/) Sensu instances, the Tessen configuration setting will automatically override to `opt-in` at runtime. +{{% /notice %}} + +You can use the `--skip-confirm` flag to skip the confirmation step: + +{{< code shell >}} +sensuctl tessen opt-out --skip-confirm +{{< /code >}} + +To opt in to Tessen: + +{{< code shell >}} +sensuctl tessen opt-in +{{< /code >}} + +## Tessen specification + +### Top-level attributes + +api_version | +-------------|------ +description | Top-level attribute that specifies the Sensu API group and version. For Tessen configuration in this version of Sensu, the `api_version` should always be `core/v2`. +required | Required for Tessen configuration in `wrapped-json` or `yaml` format for use with [`sensuctl create`][7]. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +api_version: core/v2 +{{< /code >}} +{{< code json >}} +{ + "api_version": "core/v2" +} +{{< /code >}} +{{< /language-toggle >}} + +spec | +-------------|------ +description | Top-level map that includes Tessen configuration [spec attributes][8]. +required | Required for Tessen configuration in `wrapped-json` or `yaml` format for use with [`sensuctl create`][7]. +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +spec: + opt_out: false +{{< /code >}} +{{< code json >}} +{ + "spec": { + "opt_out": false + } +} +{{< /code >}} +{{< /language-toggle >}} + +type | +-------------|------ +description | Top-level attribute that specifies the [`sensuctl create`][7] resource type. Tessen configuration should always be type `TessenConfig`. +required | Required for Tessen configuration in `wrapped-json` or `yaml` format for use with [`sensuctl create`][7]. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +type: TessenConfig +{{< /code >}} +{{< code json >}} +{ + "type": "TessenConfig" +} +{{< /code >}} +{{< /language-toggle >}} + +### Spec attributes + +opt_out | +-------------|------ +description | `true` to opt out of Tessen. Otherwise, `false`. Tessen is enabled by default on Sensu backends and required for [licensed][4] Sensu instances. +required | true +type | Boolean +default | `false` +example | {{< language-toggle >}} +{{< code yml >}} +opt_out: false +{{< /code >}} +{{< code json >}} +{ + "opt_out": false +} +{{< /code >}} +{{< /language-toggle >}} + +## Tessen configuration example + +This example is in `wrapped-json`format for use with [`sensuctl create`][7]. +To manage Tessen for unlicensed Sensu instances with the [Tessen API][2], use non-wrapped `json` format as shown in the [API docs][2]. + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: TessenConfig +api_version: core/v2 +spec: + opt_out: false +{{< /code >}} + +{{< code json >}} +{ + "type": "TessenConfig", + "api_version": "core/v2", + "spec": { + "opt_out": false + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Tessen metrics log examples + +For unlicensed instances that opt in to Tessen and all licensed instances, Sensu sends various metrics back to the Tessen service. +In the example metrics log below, Sensu is sending the number of check hooks back to the Tessen service. + +{{< code text >}} +{ + "component": "tessend", + "level": "debug", + "metric_name": "hook_count", + "metric_value": 2, + "msg": "collected a metric for tessen", + "time": "2019-09-16T09:02:11Z" +} +{{< /code >}} + +Sensu also sends other metrics, such as the number of handlers: + +{{< code text >}} +{ + "component": "tessend", + "level": "debug", + "metric_name": "handler_count", + "metric_value": 10, + "msg": "collected a metric for tessen", + "time": "2019-09-16T09:02:06Z" +} +{{< /code >}} + +Or the number of filters: + +{{< code text >}} +{ + "component": "tessend", + "level": "debug", + "metric_name": "filter_count", + "metric_value": 4, + "msg": "collected a metric for tessen", + "time": "2019-09-16T09:02:01Z" +} +{{< /code >}} + +Or the number of authentication providers, secrets providers, and secrets: + +{{< code text >}} +{ + "component": "tessend", + "level": "debug", + "metric_name": "auth_provider_count", + "metric_value": 2, + "msg": "collected a metric for tessen", + "time": "2020-03-30T15:16:42-04:00" +} +{{< /code >}} + +{{< code text >}} +{ + "component": "tessend", + "level": "debug", + "metric_name": "secret_provider_count", + "metric_value": 1, + "msg": "collected a metric for tessen", + "time": "2020-03-30T15:17:12-04:00" +} +{{< /code >}} + +{{< code text >}} +{ + "component": "tessend", + "level": "debug", + "metric_name": "secret_count", + "metric_value": 1, + "msg": "collected a metric for tessen", + "time": "2020-03-30T15:16:17-04:00" +} +{{< /code >}} + +If you opt into Tessen, you can view all of the metrics in the logs: + +{{< code shell >}} +journalctl _COMM=sensu-backend.service +{{< /code >}} + +To view the events on-disk, read [Log Sensu services with systemd][9]. + +[1]: https://sensu.io/blog/announcing-tessen-the-sensu-call-home-service +[2]: ../../../api/core/tessen/ +[3]: ../../../sensuctl/ +[4]: ../../maintain-sensu/license/ +[5]: ../../maintain-sensu/troubleshoot +[6]: ../../control-access/rbac#default-users +[7]: ../../../sensuctl/create-manage-resources/#create-resources +[8]: #spec-attributes +[9]: ../log-sensu-systemd/ diff --git a/content/sensu-go/6.12/operations/monitoring-as-code/_index.md b/content/sensu-go/6.12/operations/monitoring-as-code/_index.md new file mode 100644 index 0000000000..b903595722 --- /dev/null +++ b/content/sensu-go/6.12/operations/monitoring-as-code/_index.md @@ -0,0 +1,345 @@ +--- +title: "Monitoring as code with Sensu" +linkTitle: "Monitoring as Code" +description: "Use Sensu's end-to-end monitoring as code solution to manage monitoring and observability the same way you build and deploy apps and infrastructure." +product: "Sensu Go" +version: "6.12" +weight: 5 +layout: "single" +toc: true +menu: + sensu-go-6.12: + parent: operations + identifier: monitoring-as-code +--- + +Sensu's end-to-end monitoring as code solution allows you to manage your monitoring and observability configurations the same way you build, test, and deploy your applications and infrastructure, like Kubernetes and Terraform. +Monitoring as code combines composable building blocks with robust APIs so you can define your entire observability configuration as declarative YAML or JSON code and improve visibility, reliability, portability, and repeatability. + +When a new endpoint starts up, like a cloud compute instance or Kubernetes Pod, the endpoint's agent automatically registers it with the platform and starts collecting observability data according to the code in your configuration files. +Teams can share and remix observability configurations for collecting events and metrics, diagnosing issues, sending alerts, and automatically remediating problems. + +- Share, edit, review, and version your observability configuration files just like you would with other "as code" solutions, within one team or among teams across your organization. +- Maintain revision control and change history for your observability configurations. +- Export the Sensu configuration for one environment and replicate the same configuration in other environments. +- Remove, restore, back up, and recover Sensu instances based on your Sensu configuration files. +- Include your observability configuration in your centralized continuous integration/continuous delivery (CI/CD) pipeline to keep your configuration files aligned with your product and services. + +To get started with monitoring as code, you'll need a [repository][11] and [configuration files][13] that contain your resource definitions. + +## Create a monitoring as code repository + +Create a monitoring as code repository for the configuration files that contain the Sensu resource definitions you use for monitoring and observability. +You can use any source control repository. + +The way you will use your [configuration files][13] will help you choose the best structure for your monitoring as code repository. +For example, if you are likely to share observability components or manage your configuration files as part of your CI/CD workflow, it probably makes sense to use individual configuration files for different types of resources: one file for all of your checks, one file for all of your handlers, and so on. +If you want to facilitate more granular sharing, you can save one resource definition per file. + +If you want to share complete end-to-end observability configurations with your colleagues, you might save all of the resource definitions for each observability configuration in a single configuration file. +This allows others to read through an entire configuration without interruption, and it's convenient for demonstrating a complete Sensu configuration. +However, a single configuration file that includes every resource type isn't the best structure for CI/CD management or sharing resources among teams. + +[SensuFlow][5], our GitHub Action for managing Sensu resources via repository commits, requires a repository structure organized by clusters and namespaces. +All resources of each type for each namespace are saved in a single configuration file: + +{{< code text >}} +.sensu/ + cluster/ + namespaces.yml + namespaces/ + / + checks/ + hooks/ + filters/ + handlers/ + handlersets/ + mutators/ + pipelines/ +{{< /code >}} + +## Adopt a configuration file strategy + +Configuration files contain your Sensu resource definitions. +You can [build configuration files as you go][6], adding resource definitions as you create them. +You can also create your entire observability configuration first, then [export some or all of your resource definitions][7] to a file. +Or, you can use a mix: export all of your existing resource definitions to configuration files and append new resources as you create them. + +When you are ready to replicate your exported resource definitions, use [`sensuctl create`][10]. + +{{% notice note %}} +**NOTE**: You cannot replicate API key or user resources from a `sensuctl dump` export.

    +API keys must be reissued, but you can use your exported configuration file as a reference for granting new API keys to replace the exported keys.

    +When you export users, required password attributes are not included. +You must add a [`password_hash`](../../sensuctl/#generate-a-password-hash) or `password` to `users` resources before replicating them with the `sensuctl create` command. +{{% /notice %}} + +### Build as you go + +To build as you go, use sensuctl commands to retrieve your Sensu resource definitions as you create them and copy the definitions into your configuration files. + +For example, if you follow [Monitor server resources][8] and create a check named `check_cpu`, you can retrieve that check definition in YAML or JSON format with sensuctl: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl check info check_cpu --format yaml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl check info check_cpu --format wrapped-json +{{< /code >}} + +{{< /language-toggle >}} + +The sensuctl response will include the complete `check_cpu` resource definition in the specified format: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: check_cpu +spec: + check_hooks: null + command: check-cpu-usage -w 75 -c 90 + env_vars: null + handlers: null + high_flap_threshold: 0 + interval: 60 + low_flap_threshold: 0 + output_metric_format: "" + output_metric_handlers: null + pipelines: + - api_version: core/v2 + name: reduce_alerts + type: Pipeline + proxy_entity_name: "" + publish: true + round_robin: false + runtime_assets: + - check-cpu-usage + secrets: null + stdin: false + subdue: null + subscriptions: + - system + timeout: 0 + ttl: 0 +{{< /code >}} + +{{< code json >}} +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "check_cpu" + }, + "spec": { + "check_hooks": null, + "command": "check-cpu-usage -w 75 -c 90", + "env_vars": null, + "handlers": null, + "high_flap_threshold": 0, + "interval": 60, + "low_flap_threshold": 0, + "output_metric_format": "", + "output_metric_handlers": null, + "pipelines": [ + { + "api_version": "core/v2", + "name": "reduce_alerts", + "type": "Pipeline" + } + ], + "proxy_entity_name": "", + "publish": true, + "round_robin": false, + "runtime_assets": [ + "check-cpu-usage" + ], + "secrets": null, + "stdin": false, + "subdue": null, + "subscriptions": [ + "system" + ], + "timeout": 0, + "ttl": 0 + } +} +{{< /code >}} + +{{< /language-toggle >}} + +If you prefer, you can also [view JSON resource definitions in the Sensu web UI][14]. + +You can copy these resource definitions and paste them into manually created configuration files located anywhere on your system. + +Alternatively, you can view resource definitions and copy them into a new or existing configuration file with a single sensuctl command. +To use the following examples, replace `` with the resource type (like `check`) and replace `` with the name of the resource (like `check_cpu`). + +- Copy the resource defintion to a new file (or overwrite an existing file with the same name): + + {{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl info --format yaml > resource.yml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl info --format wrapped-json > resource.json +{{< /code >}} + +{{< /language-toggle >}} + +- Copy the resource defintion to a new file (or overwrite an existing file with the same name) and show the resource definition in stdout: + + {{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl info --format yaml | tee resource.yml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl info --format wrapped-json | tee resource.json +{{< /code >}} + +{{< /language-toggle >}} + +- Append the resource defintion to an existing file: + + {{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl info --format yaml >> resource.yml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl info --format wrapped-json >> resource.json +{{< /code >}} + +{{< /language-toggle >}} + +- Append the resource defintion to an existing file and show the resource definition in stdout: + + {{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl info --format yaml | tee -a resource.yml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl info --format wrapped-json | tee -a resource.json +{{< /code >}} + +{{< /language-toggle >}} + +### Export existing resources + +If you've already created observability resources, use `sensuctl dump` to create a copy of your existing resource definitions. + +First, create a sensu directory: + +{{< code shell >}} +mkdir sensu +{{< /code >}} + +Then, copy your observability resource definitions according to the [repository structure][11] you are using. +For example, if you want to save resources according to type and namespace, this command will save all of your check definitions for the `production` namespace in one configuration file: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl dump core/v2.CheckConfig \ +--namespace production \ +--format yaml | > sensu/namespaces/production/checks.yml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl dump core/v2.CheckConfig \ +--namespace production \ +--format wrapped-json | > sensu/namespaces/production/checks.json +{{< /code >}} + +{{< /language-toggle >}} + +Repeat this command for each resource type in each of your namespaces. + +#### Strip namespaces from resource definitions + +To [replicate and reuse resources][5] in any namespace without manual editing, create a copy of your existing resources with the namespaces stripped from their definitions: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl dump all \ +--all-namespaces \ +--format yaml | grep -v "^\s*namespace:" > sensu/resources.yml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl dump all \ +--all-namespaces \ +--format wrapped-json | grep -v "^\s*namespace:" > sensu/resources.json +{{< /code >}} + +{{< /language-toggle >}} + +## Best practices for monitoring as code + +Sensu's monitoring as code solution is flexible — you can use any source control repository and choose your own directory structure — but following a few best practices will contribute to a successful implementation. + +- To maintain consistency, save all of your resources as only one file type: YAML or JSON. +- Include all dependencies within a resource definition. +For example, if a handler requires a dynamic runtime asset and a secret, include the asset and secret definitions with the definition for the handler itself. +- Choose the labels you use in your resource definitions with care. +CI/CD systems like [SensuFlow][5] rely on labels to determine which resources to delete, so if all of your resources have the same labels, you could delete resources you didn't intend to be managed in a particular CI/CD workflow. +- Establish a resource-labeling schema throughout your organization to facilitate CI/CD. +Following the same method for applying labels helps keep unmanaged Sensu resources from multiplying and allows different teams to confidently deploy their own CI/CD workflows without the risk of accidentally deleting another team's resources. + +## Implement CI/CD with monitoring as code + +When you're ready, expand your monitoring as code practices to include managing your Sensu configuration files with a CI/CD workflow. +CI/CD takes the manual work out of maintaining and updating your monitoring as code repository so that any updates to the Sensu resources in your monitoring as code repository are reflected in your Sensu configuration in a timely manner. + +If you’re already using CI/CD, you already have workflows for versioning, building, testing, and deploying your code. +Integrating monitoring as code means your monitoring and observability can go through those same CI/CD workflows. + +There's no one "correct" way to implement CI/CD with monitoring as code, but the [SensuFlow GitHub Action][5] offers a turnkey reference implementation that helps you create your own monitoring as code workflow and start managing Sensu resources via repository commits. + +### Use SensuFlow for CI/CD monitoring as code + +SensuFlow is a git-based, prescriptive monitoring as code workflow that uses [sensuctl][2] (including [sensuctl prune][3]) to synchronize your monitoring and observability code with your Sensu deployments. + +{{% notice note %}} +**NOTE**: SensuFlow is available for technical preview, and individual components in the workflow may change. +Before you use SensuFlow in production, test it in a development environment or a dedicated test namespace in your current environment. +{{% /notice %}} + +SensuFlow requires: + +- A code repository of Sensu resource definitions +- A Sensu [role-based access control (RBAC)][4] service account with permission to manage all resources in your repository +- A resource labeling convention to designate which resources the SensuFlow workflow should manage +- Integration with your CI/CD system to run sensuctl commands as the service account user from the repository of resource definitions + +Read the [SensuFlow GitHub Action marketplace page][1] and [Monitoring as code with Sensu Go and SensuFlow][12] to get started with SensuFlow as your monitoring as code workflow. + + +[1]: https://github.com/marketplace/actions/sensuflow +[2]: ../../sensuctl/ +[3]: ../../sensuctl/create-manage-resources/#prune-resources +[4]: ../control-access/rbac/ +[5]: #use-sensuflow-for-cicd-monitoring-as-code +[6]: #build-as-you-go +[7]: #export-existing-resources +[8]: ../../observability-pipeline/observe-schedule/monitor-server-resources/ +[9]: ../../sensuctl/create-manage-resources/#create-resources-across-namespaces +[10]: ../../sensuctl/create-manage-resources/#create-resources +[11]: #create-a-monitoring-as-code-repository +[12]: https://sensu.io/blog/monitoring-as-code-with-sensu-flow +[13]: #adopt-a-configuration-file-strategy +[14]: ../../web-ui/view-manage-resources/#view-resource-data-in-the-web-ui diff --git a/content/sensu-go/6.12/platforms.md b/content/sensu-go/6.12/platforms.md new file mode 100644 index 0000000000..59c7dd487f --- /dev/null +++ b/content/sensu-go/6.12/platforms.md @@ -0,0 +1,433 @@ +--- +title: "Supported platforms and distributions" +linkTitle: "Platforms and Distributions" +description: "Get Sensu Go for your platform: Linux, Windows, macOS, FreeBSD, and Solaris. Sensu Go is available as a package, Docker image, or binary-only distribution." +weight: -60 +version: "6.12" +product: "Sensu Go" +menu: "sensu-go-6.12" +platformContent: true +platforms: ["Linux", "Windows", "macOS", "FreeBSD", "Solaris"] +--- + +Sensu is available as [packages][1], [Docker images][2], and [binary-only distributions][4]. +We recommend [installing Sensu][5] with one of our supported packages, Docker images, or [configuration management][6] integrations. +Sensu downloads are provided under the [Sensu commercial license][7]. + +## Supported packages + +This page lists supported packages for the most common platforms. +Supported packages are available from [sensu/stable][8] on packagecloud and the [Sensu downloads page][9]. + +{{% notice note %}} +**NOTE**: The [sensu/stable](https://packagecloud.io/sensu/stable/) repository on packagecloud includes packages for every platform Sensu supports, in addition to packages for the common platforms listed on this page. +{{% /notice %}} + +### Sensu backend + +| | RHEL family
    7, 8, 9 | Debian
    11, 12, 13 | Ubuntu 18.04,
    20.04, 22.04,
    24.04 | +|----------------------|---------|---|---| +| `amd64` | {{< check >}} | {{< check >}} | {{< check >}} | +| `Arm64`/`aarch64` | {{< check >}} | {{< check >}} | {{< check >}} | +| `ppc64el`/`ppc64le` | {{< check >}} | {{< check >}} | {{< check >}} | + +### Sensu agent + +| | RHEL
    family
    7, 8, 9 | Debian
    11, 12, 13 | Ubuntu
    18.04,
    20.04,
    22.04,
    24.04 | Windows 7
    and later | Windows
    Server
    2008 R2
    and later | +|----------------------|---------|---|---|---|---| +| `amd64` | {{< check >}} | {{< check >}} | {{< check >}} | {{< check >}} | {{< check >}} | +| `386` | {{< check >}} | {{< check >}} | {{< check >}} | {{< check >}} | {{< check >}} | +| `armv5` | {{< check >}} | {{< check >}} | | | | +| `armv6` | {{< check >}} | {{< check >}} | | | | +| `armv7` | {{< check >}} | {{< check >}} | {{< check >}} | | | +| `ppc64el`/`ppc64le` | {{< check >}} | {{< check >}} | {{< check >}} | | | +| `s390x` | {{< check >}} | {{< check >}} | {{< check >}} | | | + +### Sensuctl command line tool + +| | RHEL
    family
    7, 8, 9 | Debian
    11, 12, 13 | Ubuntu
    18.04,
    20.04,
    22.04,
    24.04 | Windows 7
    and later | Windows
    Server
    2008 R2
    and later | +|----------------------|---------|---|---|---|---| +| `amd64` | {{< check >}} | {{< check >}} | {{< check >}} | {{< check >}} | {{< check >}} | +| `386` | {{< check >}} | {{< check >}} | {{< check >}} | {{< check >}} | {{< check >}} | +| `armv5` | {{< check >}} | {{< check >}} | | | | +| `armv6` | {{< check >}} | {{< check >}} | | | | +| `armv7` | {{< check >}} | {{< check >}} | {{< check >}} | | | +| `ppc64el`/`ppc64le` | {{< check >}} | {{< check >}} | {{< check >}} | | | +| `s390x` | {{< check >}} | {{< check >}} | {{< check >}} | | | + +## Docker images + +Docker images that contain the Sensu backend and Sensu agent are available for Linux-based containers. + +| Image Name | Base +| ---------- | ------- | +| [sensu/sensu][10] | Alpine Linux +| [sensu/sensu-rhel][11] | Red Hat Enterprise Linux + +## Binary-only distributions + +Sensu binary-only distributions are available in `.zip` and `.tar.gz` formats. + +| Platform | Architectures | +|----------|---------------| +| [Linux][44] | `386` `amd64` `arm64` `armv5` `armv6` `armv7`
    `MIPS` `MIPS LE` `MIPS 64` `MIPS 64 LE` `ppc64le` `s390x` | +| [Windows][45] | `386` `amd64` | +| [macOS][46] | `amd64` `amd64 CGO` `arm64` | +| [FreeBSD][47] | `386` `amd64` `armv5` `armv6` `armv7` | +| [Solaris][48] | `amd64` | + +{{< platformBlock "Linux" >}} + +### Linux + +Sensu binary-only distributions for Linux are available for the architectures listed in the table below. + +For binary distributions, we support the following Linux kernels: + +- 3.1.x and later for `armv5` +- 4.8 and later for `MIPS 64 LE hard float` and `MIPS 64 LE soft float` +- 2.6.23 and later for all other architectures + +{{% notice note %}} +**NOTE**: The Linux `amd64`, `arm64`, and `ppc64le` binary distributions include the agent, backend, and sensuctl CLI. +Binaries for all other Linux architectures include only the Sensu agent and sensuctl CLI. +{{% /notice %}} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArchitectureFormatsArchitectureFormats
    386.tar.gz | .zipMIPS LE hard float.tar.gz | .zip
    amd64.tar.gz | .zipMIPS LE soft float.tar.gz | .zip
    arm64.tar.gz | .zipMIPS 64 hard float.tar.gz | .zip
    armv5.tar.gz | .zipMIPS 64 soft float.tar.gz | .zip
    armv6.tar.gz | .zipMIPS 64 LE hard float.tar.gz | .zip
    armv7.tar.gz | .zipMIPS 64 LE soft float.tar.gz | .zip
    MIPS hard float.tar.gz | .zips390x.tar.gz | .zip
    MIPS soft float.tar.gz | .zipppc64le.tar.gz | .zip
    + +For example, to download Sensu for Linux `amd64` in `tar.gz` format: + +{{< code shell >}} +curl -LO https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_linux_amd64.tar.gz +{{< /code >}} + +Generate a SHA-256 checksum for the downloaded artifact: + +{{< code shell >}} +sha256sum sensu-go_6.12.0_linux_amd64.tar.gz +{{< /code >}} + +The result should match the checksum for your platform: + +{{< code shell >}} +curl -LO https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_checksums.txt && cat sensu-go_6.12.0_checksums.txt +{{< /code >}} + +{{< platformBlockClose >}} + +{{< platformBlock "Windows" >}} + +#### Federal Information Processing Standard (FIPS) Compliance + +Builds that support the Federal Information Processing Standard (FIPS) for Federal Risk and Authorization Management Program (FedRAMP) compliance are available for Linux `amd64`. + +Sensu FIPS builds with FIPS-mode configuration options are linked with the FIPS 140-2 validated cryptographic library. +You can run Red Hat Enterprise Linux (RHEL) with the FIPS-mode kernel option to enforce FIPS systemwide — Sensu FIPS builds comply with this mode. + +[Contact Sensu][50] to request builds with FIPS support. + +Read [Configure Sensu for FIPS compliance][65] to learn more about Sensu's FIPS build, including configuration examples. + +### Windows + +Sensu binary-only distributions for Windows are available for the architectures listed in the table below. + +We support Windows 7 and later and Windows Server 2008R2 and later for binary distributions. + +{{% notice note %}} +**NOTE**: The Windows binary distributions include only the Sensu agent and sensuctl CLI. +{{% /notice %}} + +| Architecture | Formats | +| --- | --- | +| `386` | [`.tar.gz`][27] \| [`.zip`][29] +| `amd64` | [`.tar.gz`][26] \| [`.zip`][28] + +For example, to download Sensu for Windows `amd64` in `zip` format: + +{{< code text >}} +Invoke-WebRequest https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_windows_amd64.zip -OutFile "$env:userprofile\sensu-go_6.12.0_windows_amd64.zip" +{{< /code >}} + +Generate a SHA-256 checksum for the downloaded artifact: + +{{< code text >}} +Get-FileHash "$env:userprofile\sensu-go_6.12.0_windows_amd64.zip" -Algorithm SHA256 | Format-List +{{< /code >}} + +The result should match (with the exception of capitalization) the checksum for your platform: + +{{< code text >}} +Invoke-WebRequest https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_checksums.txt -OutFile "$env:userprofile\sensu-go_6.12.0_checksums.txt" + +Get-Content "$env:userprofile\sensu-go_6.12.0_checksums.txt" | Select-String -Pattern windows_amd64 +{{< /code >}} + +{{< platformBlockClose >}} + +{{< platformBlock "macOS" >}} + +### macOS + +Sensu binary-only distributions for macOS are available for the architectures listed in the table below. + +We support macOS 10.11 and later for binary distributions. + +{{% notice note %}} +**NOTE**: The macOS binary distributions include only the Sensu agent and sensuctl CLI. +{{% /notice %}} + +| Architecture | Formats | +| --- | --- | +| `amd64` | [`.tar.gz`][30] \| [`.zip`][31] +| `amd64 CGO` | [`.tar.gz`][58] \| [`.zip`][59] +| `arm64` | [`.tar.gz`][61] \| [`.zip`][62] + +For example, to download Sensu for macOS `amd64` in `tar.gz` format: + +{{< code shell >}} +curl -LO https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_darwin_amd64.tar.gz +{{< /code >}} + +Generate a SHA-256 checksum for the downloaded artifact: + +{{< code shell >}} +shasum -a 256 sensu-go_6.12.0_darwin_amd64.tar.gz +{{< /code >}} + +The result should match the checksum for your platform: + +{{< code shell >}} +curl -LO https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_checksums.txt && cat sensu-go_6.12.0_checksums.txt +{{< /code >}} + +Extract the archive: + +{{< code shell >}} +tar -xvf sensu-go_6.12.0_darwin_amd64.tar.gz +{{< /code >}} + +Copy the executable into your PATH: + +{{< code shell >}} +sudo cp sensuctl /usr/local/bin/ +{{< /code >}} + +{{< platformBlockClose >}} + +{{< platformBlock "FreeBSD" >}} + +### FreeBSD + +Sensu binary-only distributions for FreeBSD are available for the architectures listed in the table below. + +We support FreeBSD 11.2 and later for binary distributions. + +{{% notice note %}} +**NOTE**: The FreeBSD binary distributions include only the Sensu agent and sensuctl CLI. +{{% /notice %}} + +| Architecture | Formats | +| --- | --- | +| `386` | [`.tar.gz`][34] \| [`.zip`][35] +| `amd64` | [`.tar.gz`][32] \| [`.zip`][33] +| `armv5` | [`.tar.gz`][38] \| [`.zip`][39] +| `armv6` | [`.tar.gz`][40] \| [`.zip`][41] +| `armv7` | [`.tar.gz`][42] \| [`.zip`][43] + +For example, to download Sensu for FreeBSD `amd64` in `tar.gz` format: + +{{< code shell >}} +curl -LO https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_freebsd_amd64.tar.gz +{{< /code >}} + +Generate a SHA-256 checksum for the downloaded artifact: + +{{< code shell >}} +sha256sum sensu-go_6.12.0_freebsd_amd64.tar.gz +{{< /code >}} + +The result should match the checksum for your platform: + +{{< code shell >}} +curl -LO https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_checksums.txt && cat sensu-go_6.12.0_checksums.txt +{{< /code >}} + +{{< platformBlockClose >}} + +{{< platformBlock "Solaris" >}} + +### Solaris + +Sensu binary-only distributions for Solaris are available for the architectures listed in the table below. + +We support Solaris 11 and later (not SPARC) for binary distributions. + +{{% notice note %}} +**NOTE**: The Solaris binary distributions include only the Sensu agent. +{{% /notice %}} + +| Architecture | Formats | +| --- | --- | +| `amd64` | [`.tar.gz`][36] \| [`.zip`][37] + +For example, to download Sensu for Solaris `amd64` in `tar.gz` format: + +{{< code shell >}} +curl -LO https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_solaris_amd64.tar.gz +{{< /code >}} + +Generate a SHA-256 checksum for the downloaded artifact. + +{{< code shell >}} +sha256sum sensu-go_6.12.0_solaris_amd64.tar.gz +{{< /code >}} + +The result should match the checksum for your platform. + +{{< code shell >}} +curl -LO https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_checksums.txt && cat sensu-go_6.12.0_checksums.txt +{{< /code >}} + +{{< platformBlockClose >}} + +## Legacy systems and other platforms + +The [Sensu Push][25] utility allows you to execute Sensu checks on legacy systems and other platforms that cannot run the Sensu agent, such as AIX and SPARC Solaris. + +You can also use cron to run Sensu checks locally on these systems and forward the results to an upstream Sensu backend or agent via the [Sensu API][49]. + +## Build from source + +Sensu Go's core is open source software, freely available under an MIT License. +Sensu Go instances built from source do not include [commercial features][3] such as the web UI, single sign-on (SSO) authentication, and secrets management. +Review the [feature comparison matrix][15] to learn more. + +To build Sensu Go from source, read the [Sensu Go installation instructions on GitHub][16]. +To download and run the web UI as a separate component, visit the [Sensu Go Web GitHub repository][60]. + +## Mirror packages + +To mirror Sensu Go, follow the packagecloud instructions for [YUM][63] and [APT][64] repository mirroring. +The [sensu/stable][8] packagecloud repository hosts packages for every Sensu Go version. + + +[1]: #supported-packages +[2]: #docker-images +[3]: ../commercial/ +[4]: #binary-only-distributions +[5]: ../operations/deploy-sensu/install-sensu/ +[6]: ../operations/deploy-sensu/configuration-management/ +[7]: https://sensu.io/licenses +[8]: https://packagecloud.io/sensu/stable/ +[9]: https://sensu.io/downloads +[10]: https://hub.docker.com/r/sensu/sensu/ +[11]: https://hub.docker.com/r/sensu/sensu-rhel/ +[12]: https://github.com/sensu/grafana-sensu-go-datasource/ +[13]: https://github.com/sensu/sensu-go-chef/ +[14]: https://github.com/sensu/sensu-puppet/ +[15]: https://sensu.io/features/compare +[16]: https://github.com/sensu/sensu-go#installation +[17]: https://github.com/jaredledvina/sensu-go-ansible/ +[18]: https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_linux_armv7.tar.gz +[20]: https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_linux_amd64.zip +[21]: https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_linux_arm64.zip +[22]: https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_linux_armv5.zip +[23]: https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_linux_armv6.zip +[24]: https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_linux_armv7.zip +[25]: https://github.com/sensu/sensu-push +[26]: https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_windows_amd64.tar.gz +[27]: https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_windows_386.tar.gz +[28]: https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_windows_amd64.zip +[29]: https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_windows_386.zip +[30]: https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_darwin_amd64.tar.gz +[31]: https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_darwin_amd64.zip +[32]: https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_freebsd_amd64.tar.gz +[33]: https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_freebsd_amd64.zip +[34]: https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_freebsd_386.tar.gz +[35]: https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_freebsd_386.zip +[36]: https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_solaris_amd64.tar.gz +[37]: https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_solaris_amd64.zip +[38]: https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_freebsd_armv5.tar.gz +[39]: https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_freebsd_armv5.zip +[40]: https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_freebsd_armv6.tar.gz +[41]: https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_freebsd_armv6.zip +[42]: https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_freebsd_armv7.tar.gz +[43]: https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_freebsd_armv7.zip +[44]: #linux +[45]: #windows +[46]: #macos +[47]: #freebsd +[48]: #solaris +[49]: ../api +[50]: https://sensu.io/contact +[51]: ../observability-pipeline/observe-schedule/backend/#fips-openssl +[54]: https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_linux_amd64.tar.gz +[55]: https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_linux_arm64.tar.gz +[56]: https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_linux_armv5.tar.gz +[57]: https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_linux_armv6.tar.gz +[58]: https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/cgo/sensu-go-cgo_6.12.0_darwin_amd64.tar.gz +[59]: https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/cgo/sensu-go-cgo_6.12.0_darwin_amd64.zip +[60]: https://github.com/sensu/web#roadmap +[61]: https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_darwin_arm64.tar.gz +[62]: https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/6.12.0/sensu-go_6.12.0_darwin_arm64.zip +[63]: https://packagecloud.io/sensu/stable/mirror#yum +[64]: https://packagecloud.io/sensu/stable/mirror#apt +[65]: ../operations/deploy-sensu/secure-sensu/#optional-configure-sensu-for-fips-compliance diff --git a/content/sensu-go/6.12/plugins/_index.md b/content/sensu-go/6.12/plugins/_index.md new file mode 100644 index 0000000000..874ace564a --- /dev/null +++ b/content/sensu-go/6.12/plugins/_index.md @@ -0,0 +1,52 @@ +--- +title: "Plugins" +description: "Learn how to find, install, use, and develop Sensu plugins: executable scripts or other programs that you can use as Sensu checks, handlers, and mutators." +product: "Sensu Go" +version: "6.12" +weight: 110 +layout: "single" +toc: true +menu: + sensu-go-6.12: + identifier: plugins +--- + +Sensu plugins provide executable scripts or other programs that you can use as Sensu checks, handlers, and mutators. + +Plugins are service-specific and have different setup and configuration requirements. +Many Sensu-supported plugins include quick-start templates that you only need to edit to match your configuration. +Each plugin has self-contained documentation with in-depth information about how to install and use it. + +## Find Sensu plugins + +Use the [Sensu Catalog][10] to find and enable many plugins directly from your browser. +Follow the Catalog prompts to configure the Sensu resources you need and start processing your observability data with a few clicks. + +To find many more available Sensu plugins, search [Bonsai, the Sensu asset hub][2]. +Bonsai lists hundreds of Sensu plugins with installation instructions and usage examples. + +We also list popular Sensu plugins in the [featured integrations][3] section. + +## Write your own custom plugins + +Write your own Sensu plugins in almost any programming language with [Sensu's plugin specification][4]. +The [Sensu Go plugin SDK library][9] provides a framework for building Sensu Go plugins so that all you need to do is define plugin arguments and input validation and execution functions. + +If you are interested in sharing your plugin with other Sensu users, you can find guidance for contributing plugins, pinning versions, writing plugin READMEs, and transferring repos to community responsibility at the [Sensu plugins community GitHub repo][8] + +## Use Nagios plugins + +The [Sensu plugin specification][4] is compatible with the [Nagios plugin specification][5], so you can use Nagios plugins with Sensu without any modification. +Sensu allows you to bring new life to the 50+ plugins in the official [Nagios Plugins project][6], a mature source of monitoring plugins, and more than 4000 plugins in the [Nagios Exchange][7]. + + +[1]: developer-guidelines/ +[2]: https://bonsai.sensu.io/ +[3]: featured-integrations/ +[4]: plugins/ +[5]: https://assets.nagios.com/downloads/nagioscore/docs/nagioscore/3/en/pluginapi.html +[6]: https://www.nagios.org/downloads/nagios-plugins/ +[7]: https://exchange.nagios.org/ +[8]: https://github.com/sensu-plugins/community +[9]: https://github.com/sensu-community/sensu-plugin-sdk +[10]: ../catalog/sensu-catalog/ diff --git a/content/sensu-go/6.12/plugins/assets.md b/content/sensu-go/6.12/plugins/assets.md new file mode 100644 index 0000000000..aeb2a79593 --- /dev/null +++ b/content/sensu-go/6.12/plugins/assets.md @@ -0,0 +1,1321 @@ +--- +title: "Assets reference" +linkTitle: "Assets Reference" +reference_title: "Assets" +type: "reference" +description: "Use Sensu's dynamic runtime assets to provide the plugins, libraries, and runtimes you need to create automated monitoring and observability workflows." +weight: 20 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: plugins +--- + +Dynamic runtime assets are shareable, reusable packages that make it easier to deploy Sensu [plugins][29]. +You can use dynamic runtime assets to provide the plugins, libraries, and runtimes you need to automate your monitoring workflows. +Sensu supports dynamic runtime assets for [checks][6], [filters][7], [mutators][8], and [handlers][9]. + +Use the [Sensu Catalog][33] to find, configure, and install many dynamic runtime assets directly from your browser. +Follow the Catalog prompts to configure the Sensu resources you need and start processing your observability data with a few clicks. + +You can also discover, download, and share dynamic runtime assets using [Bonsai, the Sensu asset hub][16]. +Read [Use assets to install plugins][23] to get started. + +{{% notice note %}} +**NOTE**: Dynamic runtime assets are not required to use Sensu Go. +You can install Sensu plugins using the [sensu-install](../install-plugins/#install-plugins-with-the-sensu-install-tool) tool or a [configuration management](../../operations/deploy-sensu/configuration-management/) solution. +{{% /notice %}} + +The Sensu backend executes handler, filter, and mutator dynamic runtime assets. +The Sensu agent executes check dynamic runtime assets. +At runtime, the backend or agent sequentially evaluates dynamic runtime assets that appear in the `runtime_assets` attribute of the handler, filter, mutator, or check being executed. + +## Dynamic runtime asset example (minimum required attributes) + +This example shows a dynamic runtime asset resource definition that includes the minimum required attributes: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Asset +api_version: core/v2 +metadata: + name: check_script +spec: + builds: + - sha512: 4f926bf4328fbad2b9cac873d117f771914f4b837c9c85584c38ccf55a3ef3c2e8d154812246e5dda4a87450576b2c58ad9ab40c9e2edc31b288d066b195b21b + url: http://example.com/asset.tar.gz +{{< /code >}} + +{{< code json >}} +{ + "type": "Asset", + "api_version": "core/v2", + "metadata": { + "name": "check_script" + }, + "spec": { + "builds": [ + { + "url": "http://example.com/asset.tar.gz", + "sha512": "4f926bf4328fbad2b9cac873d117f771914f4b837c9c85584c38ccf55a3ef3c2e8d154812246e5dda4a87450576b2c58ad9ab40c9e2edc31b288d066b195b21b" + } + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Install location for dynamic runtime assets + +If you use a Sensu [package][32], dynamic runtime assets are installed at `/var/cache`. + +If you use a Sensu [Docker image][31], dynamic runtime assets are installed at `/var/lib`. + +## Dynamic runtime asset builds + +A dynamic runtime asset build is the combination of an artifact URL, SHA512 checksum, and optional [Sensu query expression][1] filters. +Each asset definition may describe one or more builds. + +{{% notice note %}} +**NOTE**: Dynamic runtime assets that provide `url` and `sha512` attributes at the top level of the `spec` scope are [single-build assets](#asset-example-single-build-deprecated), and this form of asset defintion is deprecated. +We recommend using [multiple-build asset defintions](#asset-example-multiple-builds), which specify one or more `builds` under the `spec` scope. +{{% /notice %}} + +### Asset example: Multiple builds + +This example shows the resource definition for the [sensu/check-cpu-usage][46] dynamic runtime asset, which has multiple builds: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Asset +api_version: core/v2 +metadata: + name: check-cpu-usage + labels: + annotations: + io.sensu.bonsai.url: https://bonsai.sensu.io/assets/sensu/check-cpu-usage + io.sensu.bonsai.api_url: https://bonsai.sensu.io/api/v1/assets/sensu/check-cpu-usage + io.sensu.bonsai.tier: Community + io.sensu.bonsai.version: 0.2.2 + io.sensu.bonsai.namespace: sensu + io.sensu.bonsai.name: check-cpu-usage + io.sensu.bonsai.tags: '' +spec: + builds: + - url: https://assets.bonsai.sensu.io/a7ced27e881989c44522112aa05dd3f25c8f1e49/check-cpu-usage_0.2.2_windows_amd64.tar.gz + sha512: 900cfdf28d6088b929c4bf9a121b628971edee5fa5cbc91a6bc1df3bd9a7f8adb1fcfb7b1ad70589ed5b4f5ec87d9a9a3ba95bcf2acda56b0901406f14f69fe7 + filters: + - entity.system.os == 'windows' + - entity.system.arch == 'amd64' + - url: https://assets.bonsai.sensu.io/a7ced27e881989c44522112aa05dd3f25c8f1e49/check-cpu-usage_0.2.2_darwin_amd64.tar.gz + sha512: db81ee70426114e4cd4b3f180f2b0b1e15b4bffc09d7f2b41a571be2422f4399af3fbd2fa2918b8831909ab4bc2d3f58d0aa0d7b197d3a218b2391bb5c1f6913 + filters: + - entity.system.os == 'darwin' + - entity.system.arch == 'amd64' + - url: https://assets.bonsai.sensu.io/a7ced27e881989c44522112aa05dd3f25c8f1e49/check-cpu-usage_0.2.2_linux_armv7.tar.gz + sha512: 400aacce297176e69f3a88b0aab0ddfdbe9dd6a37a673cb1774c8d4750a91cf7713a881eef26ea21d200f74cb20818161c773490139e6a6acb92cbd06dee994c + filters: + - entity.system.os == 'linux' + - entity.system.arch == 'armv7' + - url: https://assets.bonsai.sensu.io/a7ced27e881989c44522112aa05dd3f25c8f1e49/check-cpu-usage_0.2.2_linux_arm64.tar.gz + sha512: bef7802b121ac2a2a5c5ad169d6003f57d8b4f5e83eae998a0e0dd1e7b89678d4a62e678d153edacdd65fd1d0123b5f51308622690455e77cec6deccfa183397 + filters: + - entity.system.os == 'linux' + - entity.system.arch == 'arm64' + - url: https://assets.bonsai.sensu.io/a7ced27e881989c44522112aa05dd3f25c8f1e49/check-cpu-usage_0.2.2_linux_386.tar.gz + sha512: a2dcb5324952567a61d76a2e331c1c16df69ef0e0b9899515dad8d1531b204076ad0c008f59fc2f4735a5a779afb0c1baa132268c41942b203444e377fe8c8e5 + filters: + - entity.system.os == 'linux' + - entity.system.arch == '386' + - url: https://assets.bonsai.sensu.io/a7ced27e881989c44522112aa05dd3f25c8f1e49/check-cpu-usage_0.2.2_linux_amd64.tar.gz + sha512: 24539739b5eb19bbab6eda151d0bcc63a0825afdfef3bc1ec3670c7b0a00fbbb2fd006d605a7a038b32269a22026d8947324f2bc0acdf35e8563cf4cb8660d7f + filters: + - entity.system.os == 'linux' + - entity.system.arch == 'amd64' +{{< /code >}} + +{{< code json >}} +{ + "type": "Asset", + "api_version": "core/v2", + "metadata": { + "name": "check-cpu-usage", + "labels": null, + "annotations": { + "io.sensu.bonsai.url": "https://bonsai.sensu.io/assets/sensu/check-cpu-usage", + "io.sensu.bonsai.api_url": "https://bonsai.sensu.io/api/v1/assets/sensu/check-cpu-usage", + "io.sensu.bonsai.tier": "Community", + "io.sensu.bonsai.version": "0.2.2", + "io.sensu.bonsai.namespace": "sensu", + "io.sensu.bonsai.name": "check-cpu-usage", + "io.sensu.bonsai.tags": "" + } + }, + "spec": { + "builds": [ + { + "url": "https://assets.bonsai.sensu.io/a7ced27e881989c44522112aa05dd3f25c8f1e49/check-cpu-usage_0.2.2_windows_amd64.tar.gz", + "sha512": "900cfdf28d6088b929c4bf9a121b628971edee5fa5cbc91a6bc1df3bd9a7f8adb1fcfb7b1ad70589ed5b4f5ec87d9a9a3ba95bcf2acda56b0901406f14f69fe7", + "filters": [ + "entity.system.os == 'windows'", + "entity.system.arch == 'amd64'" + ] + }, + { + "url": "https://assets.bonsai.sensu.io/a7ced27e881989c44522112aa05dd3f25c8f1e49/check-cpu-usage_0.2.2_darwin_amd64.tar.gz", + "sha512": "db81ee70426114e4cd4b3f180f2b0b1e15b4bffc09d7f2b41a571be2422f4399af3fbd2fa2918b8831909ab4bc2d3f58d0aa0d7b197d3a218b2391bb5c1f6913", + "filters": [ + "entity.system.os == 'darwin'", + "entity.system.arch == 'amd64'" + ] + }, + { + "url": "https://assets.bonsai.sensu.io/a7ced27e881989c44522112aa05dd3f25c8f1e49/check-cpu-usage_0.2.2_linux_armv7.tar.gz", + "sha512": "400aacce297176e69f3a88b0aab0ddfdbe9dd6a37a673cb1774c8d4750a91cf7713a881eef26ea21d200f74cb20818161c773490139e6a6acb92cbd06dee994c", + "filters": [ + "entity.system.os == 'linux'", + "entity.system.arch == 'armv7'" + ] + }, + { + "url": "https://assets.bonsai.sensu.io/a7ced27e881989c44522112aa05dd3f25c8f1e49/check-cpu-usage_0.2.2_linux_arm64.tar.gz", + "sha512": "bef7802b121ac2a2a5c5ad169d6003f57d8b4f5e83eae998a0e0dd1e7b89678d4a62e678d153edacdd65fd1d0123b5f51308622690455e77cec6deccfa183397", + "filters": [ + "entity.system.os == 'linux'", + "entity.system.arch == 'arm64'" + ] + }, + { + "url": "https://assets.bonsai.sensu.io/a7ced27e881989c44522112aa05dd3f25c8f1e49/check-cpu-usage_0.2.2_linux_386.tar.gz", + "sha512": "a2dcb5324952567a61d76a2e331c1c16df69ef0e0b9899515dad8d1531b204076ad0c008f59fc2f4735a5a779afb0c1baa132268c41942b203444e377fe8c8e5", + "filters": [ + "entity.system.os == 'linux'", + "entity.system.arch == '386'" + ] + }, + { + "url": "https://assets.bonsai.sensu.io/a7ced27e881989c44522112aa05dd3f25c8f1e49/check-cpu-usage_0.2.2_linux_amd64.tar.gz", + "sha512": "24539739b5eb19bbab6eda151d0bcc63a0825afdfef3bc1ec3670c7b0a00fbbb2fd006d605a7a038b32269a22026d8947324f2bc0acdf35e8563cf4cb8660d7f", + "filters": [ + "entity.system.os == 'linux'", + "entity.system.arch == 'amd64'" + ] + } + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +### Asset example: Single build (deprecated) + +This example shows the resource definition for a dynamic runtime asset with a single build: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Asset +api_version: core/v2 +metadata: + name: check_cpu_linux_amd64 + labels: + origin: bonsai + annotations: + project_url: https://bonsai.sensu.io/assets/asachs01/sensu-go-cpu-check + version: 0.0.3 +spec: + url: https://assets.bonsai.sensu.io/981307deb10ebf1f1433a80da5504c3c53d5c44f/sensu-go-cpu-check_0.0.3_linux_amd64.tar.gz + sha512: 487ab34b37da8ce76d2657b62d37b35fbbb240c3546dd463fa0c37dc58a72b786ef0ca396a0a12c8d006ac7fa21923e0e9ae63419a4d56aec41fccb574c1a5d3 + filters: + - entity.system.os == 'linux' + - entity.system.arch == 'amd64' + headers: + Authorization: 'Bearer {{ .annotations.asset_token | default "N/A" }}' + X-Forwarded-For: client1, proxy1, proxy2 +{{< /code >}} + +{{< code json >}} +{ + "type": "Asset", + "api_version": "core/v2", + "metadata": { + "name": "check_cpu_linux_amd64", + "labels": { + "origin": "bonsai" + }, + "annotations": { + "project_url": "https://bonsai.sensu.io/assets/asachs01/sensu-go-cpu-check", + "version": "0.0.3" + } + }, + "spec": { + "url": "https://assets.bonsai.sensu.io/981307deb10ebf1f1433a80da5504c3c53d5c44f/sensu-go-cpu-check_0.0.3_linux_amd64.tar.gz", + "sha512": "487ab34b37da8ce76d2657b62d37b35fbbb240c3546dd463fa0c37dc58a72b786ef0ca396a0a12c8d006ac7fa21923e0e9ae63419a4d56aec41fccb574c1a5d3", + "filters": [ + "entity.system.os == 'linux'", + "entity.system.arch == 'amd64'" + ], + "headers": { + "Authorization": "Bearer {{ .annotations.asset_token | default \"N/A\" }}", + "X-Forwarded-For": "client1, proxy1, proxy2" + } + } +} +{{< /code >}} + +{{< /language-toggle >}} + +### Dynamic runtime asset build evaluation + +For each build provided in a dynamic runtime asset, Sensu will evaluate any defined filters to determine whether any build matches the agent or backend service's environment. +If all filters specified on a build evaluate to `true`, that build is considered a match. +For dynamic runtime assets with multiple builds, only the first build that matches will be downloaded and installed. + +### Dynamic runtime asset build download + +Sensu downloads the dynamic runtime asset build on the host system where the asset contents are needed to execute the requested command. +For example, if a check definition references a dynamic runtime asset, the Sensu agent that executes the check will download the asset the first time it executes the check. +The dynamic runtime asset build the agent downloads will depend on the filter rules associated with each build defined for the asset. + +Sensu backends follow a similar process when pipeline elements (filters, mutators, and handlers) request dynamic runtime asset installation as part of operation. + +{{% notice note %}} +**NOTE**: Dynamic runtime asset builds are not downloaded until they are needed for command execution. +{{% /notice %}} + +When Sensu finds a matching build, it downloads the build artifact from the specified URL. +If the asset definition includes headers, they are passed along as part of the HTTP request. +If the downloaded artifact's SHA512 checksum matches the checksum provided by the build, it is unpacked into the Sensu service's local cache directory. + +Set the backend or agent's local cache path with the `cache-dir` configuration option. +Disable dynamic runtime assets for an agent with the agent [`disable-assets`][30] configuration option. + +{{% notice note %}} +**NOTE**: Dynamic runtime asset builds are unpacked into the cache directory that is configured with the `cache-dir` configuration option. +{{% /notice %}} + +Use the `assets-rate-limit` and `assets-burst-limit` configuration options for the [agent][40] and [backend][41] to configure a global rate limit for fetching dynamic runtime assets. + +### Dynamic runtime asset build execution + +The directory path of each dynamic runtime asset listed in a check, event filter, handler, or mutator resource's `runtime_assets` array is appended to the `PATH` before the resource's `command` is executed. +Subsequent check, event filter, handler, or mutator executions look for the dynamic runtime asset in the local cache and ensure that the contents match the configured checksum. + +The following example demonstrates a use case with a Sensu check resource and an asset: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Asset +api_version: core/v2 +metadata: + name: sensu-prometheus-collector +spec: + builds: + - url: https://assets.bonsai.sensu.io/ef812286f59de36a40e51178024b81c69666e1b7/sensu-prometheus-collector_1.1.6_linux_amd64.tar.gz + sha512: a70056ca02662fbf2999460f6be93f174c7e09c5a8b12efc7cc42ce1ccb5570ee0f328a2dd8223f506df3b5972f7f521728f7bdd6abf9f6ca2234d690aeb3808 + filters: + - entity.system.os == 'linux' + - entity.system.arch == 'amd64' +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: prometheus_collector +spec: + command: "sensu-prometheus-collector -prom-url http://localhost:9090 -prom-query up" + interval: 10 + publish: true + output_metric_handlers: + - influxdb + output_metric_format: influxdb_line + runtime_assets: + - sensu-prometheus-collector + subscriptions: + - system +{{< /code >}} + +{{< code json "JSON" >}} +{ + "type": "Asset", + "api_version": "core/v2", + "metadata": { + "name": "sensu-email-handler" + }, + "spec": { + "builds": [ + { + "url": "https://assets.bonsai.sensu.io/45eaac0851501a19475a94016a4f8f9688a280f6/sensu-email-handler_0.2.0_linux_amd64.tar.gz", + "sha512": "d69df76612b74acd64aef8eed2ae10d985f6073f9b014c8115b7896ed86786128c20249fd370f30672bf9a11b041a99adb05e3a23342d3ad80d0c346ec23a946", + "filters": [ + "entity.system.os == 'linux'", + "entity.system.arch == 'amd64'" + ] + } + ] + } +} +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "prometheus_collector" + }, + "spec": { + "command": "sensu-prometheus-collector -prom-url http://localhost:9090 -prom-query up", + "handlers": [ + "influxdb" + ], + "interval": 10, + "publish": true, + "output_metric_format": "influxdb_line", + "runtime_assets": [ + "sensu-prometheus-collector" + ], + "subscriptions": [ + "system" + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Dynamic runtime asset format specification + +Sensu expects a dynamic runtime asset to be a tar archive (optionally gzipped) that contains one or more executables within a bin folder. +Any scripts or executables should be within a `bin/` folder in the archive. +Read the [Sensu Go Plugin template][28] for an example dynamic runtime asset and Bonsai configuration. + +The following are injected into the execution context: + +- `{PATH_TO_ASSET}/bin` is injected into the `PATH` environment variable +- `{PATH_TO_ASSET}/lib` is injected into the `LD_LIBRARY_PATH` environment variable +- `{PATH_TO_ASSET}/include` is injected into the `CPATH` environment variable + +{{% notice note %}} +**NOTE**: You cannot create a dynamic runtime asset by creating an archive of an existing project (as in previous versions of Sensu for plugins from the [Sensu Plugins community](https://github.com/sensu-plugins/)). +Follow the steps outlined in [Contributing Assets for Existing Ruby Sensu Plugins](https://discourse.sensu.io/t/contributing-assets-for-existing-ruby-sensu-plugins/1165), a Sensu Discourse guide. +For further examples of Sensu users who have added the ability to use a community plugin as a dynamic runtime asset, read [this Discourse post](https://discourse.sensu.io/t/how-to-use-the-sensu-plugins-kubernetes-plugin/1286). +{{% /notice %}} + +### Default cache directory + +system | sensu-backend | sensu-agent +--------|---------------------------------------|------------- +Linux | `/var/cache/sensu/sensu-backend` | `/var/cache/sensu/sensu-agent` +Windows | N/A | `C:\ProgramData\sensu\cache\sensu-agent` + +If the requested dynamic runtime asset is not in the local cache, it is downloaded from the asset URL. +The Sensu backend acts as an index of dynamic runtime asset builds, and does not provide storage or hosting for the build artifacts. +Sensu expects dynamic runtime assets to be retrieved over HTTP or HTTPS. + +### Example dynamic runtime asset structure + +{{< code text >}} +sensu-example-handler_1.0.0_linux_amd64 +├── CHANGELOG.md +├── LICENSE +├── README.md +└── bin + └── my-check.sh +└── lib +└── include +{{< /code >}} + +## Dynamic runtime asset path + +When you download and install a dynamic runtime asset, the asset files are saved to a local path on disk. +Most of the time, you won't need to know this path — except in cases where you need to provide the full path to dynamic runtime asset files as part of a command argument. + +The dynamic runtime asset directory path includes the asset's checksum, which changes every time underlying asset artifacts are updated. +This would normally require you to manually update the commands for any of your checks, handlers, hooks, or mutators that consume the dynamic runtime asset. +However, because the dynamic runtime asset directory path is exposed to asset consumers via [environment variables][14] and the [`assetPath` custom function][17], you can avoid these manual updates. + +You can retrieve the dynamic runtime asset's path as an environment variable in the `command` context for checks, handlers, hooks, and mutators. +Token substitution with the `assetPath` custom function is only available for check and hook commands. + +The Sensu Windows agent uses `cmd.exe` for the check execution environment. +For all other operating systems, the Sensu agent uses the Bourne shell (sh). + +### Environment variables for dynamic runtime asset paths + +For each dynamic runtime asset, a corresponding environment variable will be available in the `command` context. + +Sensu generates the environment variable name by capitalizing the dynamic runtime asset's complete name, replacing any special characters with underscores, and appending the `_PATH` suffix. +The value of the variable will be the path on disk where the dynamic runtime asset build has been unpacked. + +Each asset page in Bonsai lists the asset's complete name. +This example shows where the complete name for the [sensu/http-checks][22] dynamic runtime asset is located in Bonsai: + +{{< figure src="/images/go/assets_reference/complete_name_location_bonsai_asset_paths.png" alt="Bonsai page for the Sensu http-checks dynamic runtime asset showing the location of the asset namespace and name" link="/images/go/assets_reference/complete_name_location_bonsai_asset_paths.png" target="_blank" >}} + +An asset's complete name includes both the part before the forward slash (sometimes called the Bonsai namespace) and the part after the forward slash. + +Consequently, the environment variable for the [sensu/http-checks][22] asset path is: + +{{< code shell >}} +SENSU_HTTP_CHECKS_PATH +{{< /code >}} + +#### Linux environment variable example + +The Linux environment interprets the content between the `${` and `}` characters as an environment variable name and will substitute the value of that environment variable. + +For example, to reference the path for the [sensu/http-checks][22] asset in your checks, handlers, hooks, and mutators: + +{{< code shell >}} +${SENSU_HTTP_CHECKS_PATH} +{{< /code >}} + +#### Windows environment variable example + +The Windows console environment interprets the content between [paired `%` characters][44] as an environment variable name and will substitute the value of that [environment variable][45]. + +For example, to reference the path for the [sensu/sensu-windows-powershell-checks][4] asset in your checks, handlers, hooks, and mutators: + +{{< code shell "Environment variable" >}} +%SENSU_SENSU_WINDOWS_POWERSHELL_CHECKS_PATH% +{{< /code >}} + +### assetPath function for dynamic runtime asset paths + +The `assetPath` token subsitution function allows you to substitute a dynamic runtime asset's local path on disk so that you will not need to manually update your check or hook commands every time the asset is updated. + +{{% notice note %}} +**NOTE**: The `assetPath` function is only available where token substitution is available: the `command` attribute of a check or hook resource. +To access a dynamic runtime asset path in a handler or mutator command, you must use the [environment variable](#environment-variables-for-dynamic-runtime-asset-paths). +{{% /notice %}} + +#### Linux assetPath example + +To use the `assetPath` token substitution function in a Linux environment, place it immediately after the `$` character. + +For example, to use the `assetPath` function to reference the path for the [sensu/http-checks][22] asset in your check or hook resources: + +{{< code shell >}} +${{assetPath "sensu/http-checks"}} +{{< /code >}} + +#### Windows assetPath example + +To use the `assetPath` token substitution function in a Linux environment, place it between [paired `%` characters][44]. + +For example, to use the `assetPath` function to reference the path for the [sensu/sensu-windows-powershell-checks][4] asset in your check or hook resources: + +{{< code shell "assetPath" >}} +%{{assetPath "sensu/sensu-windows-powershell-checks"}}% +{{< /code >}} + +When running PowerShell plugins on Windows, the [exit status codes that Sensu captures may not match the expected values][13]. +To correctly capture exit status codes from PowerShell plugins distributed as dynamic runtime assets, use the asset path to construct the command. +The following example uses the `assetPath` function for this purpose: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: win-cpu-check +spec: + command: powershell.exe -ExecutionPolicy ByPass -f %{{assetPath "sensu/sensu-windows-powershell-checks"}}%\bin\check-windows-cpu-load.ps1 90 95 + subscriptions: + - windows + handlers: + - slack + - email + runtime_assets: + - sensu/sensu-windows-powershell-checks + interval: 10 + publish: true +{{< /code >}} + +{{< code json >}} +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "win-cpu-check" + }, + "spec": { + "command": "powershell.exe -ExecutionPolicy ByPass -f %{{assetPath \"sensu/sensu-windows-powershell-checks\"}}%\\bin\\check-windows-cpu-load.ps1 90 95", + "subscriptions": [ + "windows" + ], + "handlers": [ + "slack", + "email" + ], + "runtime_assets": [ + "sensu/sensu-windows-powershell-checks" + ], + "interval": 10, + "publish": true + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Asset hello world Bourne shell example + +In this example, you'll run a script that outputs `Hello World`: + +{{< code shell >}} +hello-world.sh + +#!/bin/sh + +STRING="Hello World" + +echo $STRING + +if [ $? -eq 0 ]; then + exit 0 +else + exit 2 +fi +{{< /code >}} + +The first step is to ensure that your directory structure is in place. +As noted in [Example dynamic runtime asset structure][15], your script could live in three potential directories in the project: `/bin`, `/lib`, or `/include`. +For this example, put your script in the `/bin` directory. + +1. Create the directory `sensu-go-hello-world`: +{{< code shell >}} +mkdir sensu-go-hello-world +{{< /code >}} + +2. Navigate to the `sensu-go-hello-world` directory: +{{< code shell >}} +cd sensu-go-hello-world +{{< /code >}} + +3. Create the directory `/bin`: +{{< code shell >}} +mkdir bin +{{< /code >}} + +4. Copy the script into the `/bin` directory: +{{< code shell >}} +cp hello-world.sh bin/ +{{< /code >}} + +5. Confirm that the script is in the `/bin` directory: +{{< code shell >}} +tree +{{< /code >}} + + The response should list the `hello-world.sh` script in the `/bin` directory: + {{< code text >}} +. +└── bin + └── hello-world.sh +{{< /code >}} + + If you receive a `command not found` response, install `tree` and run the command again. + +6. Make sure that the script is marked as executable: +{{< code shell >}} +chmod +x bin/hello-world.sh +{{< /code >}} + + If you do not receive a response, the command was successful. + +Now that the script is in the directory, move on to the next step: packaging the `sensu-go-hello-world` directory as a dynamic runtime asset tarball. + +### Package the dynamic runtime asset + +Dynamic runtime assets are archives, so packaging the asset requires creating a tar.gz archive of your project. + +1. Navigate to the directory you want to tar up. + +2. Create the tar.gz archive: +{{< code shell >}} +tar -C sensu-go-hello-world -cvzf sensu-go-hello-world-0.0.1.tar.gz . +{{< /code >}} + +3. Generate a SHA512 sum for the tar.gz archive (this is required for the dynamic runtime asset to work): +{{< code shell >}} +sha512sum sensu-go-hello-world-0.0.1.tar.gz | tee sha512sum.txt +{{< /code >}} + +From here, you can host your dynamic runtime asset wherever you’d like. +To make the asset available via [Bonsai][16], you’ll need to host it on GitHub. +Learn more in [The “Hello World” of Sensu Assets][18] at the Sensu Community Forum on Discourse. + +To host your dynamic runtime asset on a different platform like Gitlab or Bitbucket, upload your asset there. +You can also use Artifactory or even Apache or NGINX to serve your asset. +All that’s required for your dynamic runtime asset to work is the URL to the asset and the SHA512 sum for the asset to be downloaded. + +## Asset specification + +### Top-level attributes + +type | +-------------|------ +description | Top-level attribute that specifies the [`sensuctl create`][11] resource type. Dynamic runtime assets should always be type `Asset`. +required | Required for asset definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][11]. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +type: Asset +{{< /code >}} +{{< code json >}} +{ + "type": "Asset" +} +{{< /code >}} +{{< /language-toggle >}} + +api_version | +-------------|------ +description | Top-level attribute that specifies the Sensu API group and version. For dynamic runtime assets in this version of Sensu, the `api_version` should always be `core/v2`. +required | Required for asset definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][11]. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +api_version: core/v2 +{{< /code >}} +{{< code json >}} +{ + "api_version": "core/v2" +} +{{< /code >}} +{{< /language-toggle >}} + +metadata | +-------------|------ +description | Top-level collection of metadata about the dynamic runtime asset, including `name`, `namespace`, and `created_by` as well as custom `labels` and `annotations`. The `metadata` map is always at the top level of the asset definition. This means that in `wrapped-json` and `yaml` formats, the `metadata` scope occurs outside the `spec` scope. Read [metadata attributes][5] for details. +required | Required for asset definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][11]. +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +metadata: + name: check_script + namespace: default + created_by: admin + labels: + region: us-west-1 + annotations: + playbook: www.example.url +{{< /code >}} +{{< code json >}} +{ + "metadata": { + "name": "check_script", + "namespace": "default", + "created_by": "admin", + "labels": { + "region": "us-west-1" + }, + "annotations": { + "playbook": "www.example.url" + } + } +} +{{< /code >}} +{{< /language-toggle >}} + +spec | +-------------|------ +description | Top-level map that includes the dynamic runtime asset [spec attributes][12]. +required | Required for asset definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][11]. +type | Map of key-value pairs +example (multiple builds) | {{< language-toggle >}} +{{< code yml >}} +spec: + builds: + - url: http://example.com/asset-linux-amd64.tar.gz + sha512: 487ab34b37da8ce76d2657b62d37b35fbbb240c3546dd463fa0c37dc58a72b786ef0ca396a0a12c8d006ac7fa21923e0e9ae63419a4d56aec41fccb574c1a5d3 + filters: + - entity.system.os == 'linux' + - entity.system.arch == 'amd64' + headers: + Authorization: Bearer {{ .annotations.asset_token | default "N/A" }} + X-Forwarded-For: client1, proxy1, proxy2 + - url: http://example.com/asset-linux-armv7.tar.gz + sha512: 70df8b7e9aa36cf942b972e1781af04815fa560441fcdea1d1538374066a4603fc5566737bfd6c7ffa18314edb858a9f93330a57d430deeb7fd6f75670a8c68b + filters: + - entity.system.os == 'linux' + - entity.system.arch == 'arm' + - entity.system.arm_version == 7 + headers: + Authorization: Bearer {{ .annotations.asset_token | default "N/A" }} + X-Forwarded-For: client1, proxy1, proxy2 +{{< /code >}} +{{< code json >}} +{ + "spec": { + "builds": [ + { + "url": "http://example.com/asset-linux-amd64.tar.gz", + "sha512": "487ab34b37da8ce76d2657b62d37b35fbbb240c3546dd463fa0c37dc58a72b786ef0ca396a0a12c8d006ac7fa21923e0e9ae63419a4d56aec41fccb574c1a5d3", + "filters": [ + "entity.system.os == 'linux'", + "entity.system.arch == 'amd64'" + ], + "headers": { + "Authorization": "Bearer {{ .annotations.asset_token | default \"N/A\" }}", + "X-Forwarded-For": "client1, proxy1, proxy2" + } + }, + { + "url": "http://example.com/asset-linux-armv7.tar.gz", + "sha512": "70df8b7e9aa36cf942b972e1781af04815fa560441fcdea1d1538374066a4603fc5566737bfd6c7ffa18314edb858a9f93330a57d430deeb7fd6f75670a8c68b", + "filters": [ + "entity.system.os == 'linux'", + "entity.system.arch == 'arm'", + "entity.system.arm_version == 7" + ], + "headers": { + "Authorization": "Bearer {{ .annotations.asset_token | default \"N/A\" }}", + "X-Forwarded-For": "client1, proxy1, proxy2" + } + } + ] + } +} +{{< /code >}} +{{< /language-toggle >}} +example (single build, deprecated) | {{< language-toggle >}} +{{< code yml >}} +spec: + url: http://example.com/asset.tar.gz + sha512: 4f926bf4328fbad2b9cac873d117f771914f4b837c9c85584c38ccf55a3ef3c2e8d154812246e5dda4a87450576b2c58ad9ab40c9e2edc31b288d066b195b21b + filters: + - entity.system.os == 'linux' + - entity.system.arch == 'amd64' + headers: + Authorization: Bearer {{ .annotations.asset_token | default "N/A" }} + X-Forwarded-For: client1, proxy1, proxy2 +{{< /code >}} +{{< code json >}} +{ + "spec": { + "url": "http://example.com/asset.tar.gz", + "sha512": "4f926bf4328fbad2b9cac873d117f771914f4b837c9c85584c38ccf55a3ef3c2e8d154812246e5dda4a87450576b2c58ad9ab40c9e2edc31b288d066b195b21b", + "filters": [ + "entity.system.os == 'linux'", + "entity.system.arch == 'amd64'" + ], + "headers": { + "Authorization": "Bearer {{ .annotations.asset_token | default \"N/A\" }}", + "X-Forwarded-For": "client1, proxy1, proxy2" + } + } +} +{{< /code >}} +{{< /language-toggle >}} + +### Metadata attributes + +name | | +-------------|------ +description | Unique name of the dynamic runtime asset, validated with Go regex [`\A[\w\.\-]+\z`][19]. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +name: check_script +{{< /code >}} +{{< code json >}} +{ + "name": "check_script" +} +{{< /code >}} +{{< /language-toggle >}} + +| namespace | | +-------------|------ +description | [Sensu RBAC namespace][2] that the dynamic runtime asset belongs to. +required | false +type | String +default | `default` +example | {{< language-toggle >}} +{{< code yml >}} +namespace: production +{{< /code >}} +{{< code json >}} +{ + "namespace": "production" +} +{{< /code >}} +{{< /language-toggle >}} + +| created_by | | +-------------|------ +description | Username of the Sensu user who created the dynamic runtime asset or last updated the asset. Sensu automatically populates the `created_by` field when the dynamic runtime asset is created or updated. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +created_by: admin +{{< /code >}} +{{< code json >}} +{ + "created_by": "admin" +} +{{< /code >}} +{{< /language-toggle >}} + +| labels | | +-------------|------ +description | Custom attributes to include with observation event data that you can use for response and web UI view filtering.

    If you include labels in your event data, you can filter [API responses][20], [sensuctl responses][21], and [web UI views][39] based on them. In other words, labels allow you to create meaningful groupings for your data.

    Limit labels to metadata you need to use for response filtering. For complex, non-identifying metadata that you will *not* need to use in response filtering, use annotations rather than labels. +required | false +type | Map of key-value pairs. Keys can contain only letters, numbers, and underscores and must start with a letter. Values can be any valid UTF-8 string. +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +labels: + environment: development + region: us-west-2 +{{< /code >}} +{{< code json >}} +{ + "labels": { + "environment": "development", + "region": "us-west-2" + } +} +{{< /code >}} +{{< /language-toggle >}} + +| annotations | | +-------------|------ +description | Non-identifying metadata to include with observation event data that you can access with [event filters][7]. You can use annotations to add data that's meaningful to people or external tools that interact with Sensu.

    In contrast to labels, you cannot use annotations in [API response filtering][20], [sensuctl response filtering][21], or [web UI views][39]. +required | false +type | Map of key-value pairs. Keys and values can be any valid UTF-8 string. +default | `null` +example | {{< language-toggle >}} +{{< code yml >}} +annotations: + managed-by: ops + playbook: www.example.url +{{< /code >}} +{{< code json >}} +{ + "annotations": { + "managed-by": "ops", + "playbook": "www.example.url" + } +} +{{< /code >}} +{{< /language-toggle >}} + +### Spec attributes + +builds | +-------------|------ +description | List of dynamic runtime asset builds used to define multiple artifacts that provide the named asset. +required | true, if `url`, `sha512` and `filters` are not provided +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +builds: +- url: http://example.com/asset-linux-amd64.tar.gz + sha512: 487ab34b37da8ce76d2657b62d37b35fbbb240c3546dd463fa0c37dc58a72b786ef0ca396a0a12c8d006ac7fa21923e0e9ae63419a4d56aec41fccb574c1a5d3 + filters: + - entity.system.os == 'linux' + - entity.system.arch == 'amd64' +- url: http://example.com/asset-linux-armv7.tar.gz + sha512: 70df8b7e9aa36cf942b972e1781af04815fa560441fcdea1d1538374066a4603fc5566737bfd6c7ffa18314edb858a9f93330a57d430deeb7fd6f75670a8c68b + filters: + - entity.system.os == 'linux' + - entity.system.arch == 'arm' + - entity.system.arm_version == 7 +{{< /code >}} +{{< code json >}} +{ + "builds": [ + { + "url": "http://example.com/asset-linux-amd64.tar.gz", + "sha512": "487ab34b37da8ce76d2657b62d37b35fbbb240c3546dd463fa0c37dc58a72b786ef0ca396a0a12c8d006ac7fa21923e0e9ae63419a4d56aec41fccb574c1a5d3", + "filters": [ + "entity.system.os == 'linux'", + "entity.system.arch == 'amd64'" + ] + }, + { + "url": "http://example.com/asset-linux-armv7.tar.gz", + "sha512": "70df8b7e9aa36cf942b972e1781af04815fa560441fcdea1d1538374066a4603fc5566737bfd6c7ffa18314edb858a9f93330a57d430deeb7fd6f75670a8c68b", + "filters": [ + "entity.system.os == 'linux'", + "entity.system.arch == 'arm'", + "entity.system.arm_version == 7" + ] + } + ] +} +{{< /code >}} +{{< /language-toggle >}} + +url | +-------------|------ +description | URL location of the dynamic runtime asset. You can use [token substitution][3] in the URLs of your asset definitions so each backend or agent can download dynamic runtime assets from the appropriate URL without duplicating your assets (for example, if you want to host your assets at different datacenters). +required | true, unless `builds` are provided +type | String +example | {{< language-toggle >}} +{{< code yml >}} +url: http://example.com/asset.tar.gz +{{< /code >}} +{{< code json >}} +{ + "url": "http://example.com/asset.tar.gz" +} +{{< /code >}} +{{< /language-toggle >}} + +sha512 | +-------------|------ +description | Checksum of the dynamic runtime asset. +required | true, unless `builds` are provided +type | String +example | {{< language-toggle >}} +{{< code yml >}} +sha512: 4f926bf4328... +{{< /code >}} +{{< code json >}} +{ + "sha512": "4f926bf4328..." +} +{{< /code >}} +{{< /language-toggle >}} + + + +filters | +-------------|------ +description | Set of [Sensu query expressions][1] used to determine if the dynamic runtime asset should be installed. If multiple expressions are included, each expression must return `true` for Sensu to install the asset.

    Filters for _check_ dynamic runtime assets should match agent entity platforms. Filters for _handler_ and _filter_ dynamic runtime assets should match your Sensu backend platform. You can create asset filter expressions using any supported [entity.system attributes][10], including `os`, `arch`, `platform`, and `platform_family`. {{% notice protip %}} +**PRO TIP**: Dynamic runtime asset filters let you reuse checks across platforms safely. Assign dynamic runtime assets for multiple platforms to a single check, and rely on asset filters to ensure that only the appropriate asset is installed on each agent. +{{% /notice %}} +required | false +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +filters: +- entity.system.os=='linux' +- entity.system.arch=='amd64' +{{< /code >}} +{{< code json >}} +{ + "filters": [ + "entity.system.os=='linux'", + "entity.system.arch=='amd64'" + ] +} +{{< /code >}} +{{< /language-toggle >}} + +headers | | +--------------|-------| +description | HTTP headers to apply to dynamic runtime asset retrieval requests. You can use headers to access secured dynamic runtime assets. For headers that require multiple values, separate the values with a comma. You can use [token substitution][3] in your dynamic runtime asset headers (for example, to include secure information for authentication). +required | false +type | Map of key-value string pairs +example | {{< language-toggle >}} +{{< code yml >}} +headers: + Authorization: Bearer {{ .annotations.asset_token | default "N/A" }} + X-Forwarded-For: client1, proxy1, proxy2 +{{< /code >}} +{{< code json >}} +{ + "headers": { + "Authorization": "Bearer {{ .annotations.asset_token | default \"N/A\" }}", + "X-Forwarded-For": "client1, proxy1, proxy2" + } +} +{{< /code >}} +{{< /language-toggle >}} + +## Dynamic runtime asset filters based on entity.system attributes + +Use the [entity.system attributes][10] in dynamic runtime asset [filters][42] to specify which systems and configurations an asset or asset builds can be used with. + +For example, the [sensu/sensu-ruby-runtime][43] dynamic runtime asset definition includes several builds, each with filters for several `entity.system` attributes: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Asset +api_version: core/v2 +metadata: + name: sensu-ruby-runtime + labels: + annotations: + io.sensu.bonsai.url: https://bonsai.sensu.io/assets/sensu/sensu-ruby-runtime + io.sensu.bonsai.api_url: https://bonsai.sensu.io/api/v1/assets/sensu/sensu-ruby-runtime + io.sensu.bonsai.tier: Community + io.sensu.bonsai.version: 0.0.10 + io.sensu.bonsai.namespace: sensu + io.sensu.bonsai.name: sensu-ruby-runtime + io.sensu.bonsai.tags: '' +spec: + builds: + - url: https://assets.bonsai.sensu.io/5123017d3dadf2067fa90fc28275b92e9b586885/sensu-ruby-runtime_0.0.10_ruby-2.4.4_centos6_linux_amd64.tar.gz + sha512: cbee19124b7007342ce37ff9dfd4a1dde03beb1e87e61ca2aef606a7ad3c9bd0bba4e53873c07afa5ac46b0861967a9224511b4504dadb1a5e8fb687e9495304 + filters: + - entity.system.os == 'linux' + - entity.system.arch == 'amd64' + - entity.system.platform_family == 'rhel' + - parseInt(entity.system.platform_version.split('.')[0]) == 6 + - url: https://assets.bonsai.sensu.io/5123017d3dadf2067fa90fc28275b92e9b586885/sensu-ruby-runtime_0.0.10_ruby-2.4.4_debian_linux_amd64.tar.gz + sha512: a28952fd93fc63db1f8988c7bc40b0ad815eb9f35ef7317d6caf5d77ecfbfd824a9db54184400aa0c81c29b34cb48c7e8c6e3f17891aaf84cafa3c134266a61a + filters: + - entity.system.os == 'linux' + - entity.system.arch == 'amd64' + - entity.system.platform_family == 'debian' + - url: https://assets.bonsai.sensu.io/5123017d3dadf2067fa90fc28275b92e9b586885/sensu-ruby-runtime_0.0.10_ruby-2.4.4_alpine_linux_amd64.tar.gz + sha512: 8d768d1fba545898a8d09dca603457eb0018ec6829bc5f609a1ea51a2be0c4b2d13e1aa46139ecbb04873449e4c76f463f0bdfbaf2107caf37ab1c8db87d5250 + filters: + - entity.system.os == 'linux' + - entity.system.arch == 'amd64' + - entity.system.platform == 'alpine' + - entity.system.platform_version.split('.')[0] == '3' +{{< /code >}} + +{{< code json >}} +{ + "type": "Asset", + "api_version": "core/v2", + "metadata": { + "name": "sensu-ruby-runtime", + "labels": null, + "annotations": { + "io.sensu.bonsai.url": "https://bonsai.sensu.io/assets/sensu/sensu-ruby-runtime", + "io.sensu.bonsai.api_url": "https://bonsai.sensu.io/api/v1/assets/sensu/sensu-ruby-runtime", + "io.sensu.bonsai.tier": "Community", + "io.sensu.bonsai.version": "0.0.10", + "io.sensu.bonsai.namespace": "sensu", + "io.sensu.bonsai.name": "sensu-ruby-runtime", + "io.sensu.bonsai.tags": "" + } + }, + "spec": { + "builds": [ + { + "url": "https://assets.bonsai.sensu.io/5123017d3dadf2067fa90fc28275b92e9b586885/sensu-ruby-runtime_0.0.10_ruby-2.4.4_centos6_linux_amd64.tar.gz", + "sha512": "cbee19124b7007342ce37ff9dfd4a1dde03beb1e87e61ca2aef606a7ad3c9bd0bba4e53873c07afa5ac46b0861967a9224511b4504dadb1a5e8fb687e9495304", + "filters": [ + "entity.system.os == 'linux'", + "entity.system.arch == 'amd64'", + "entity.system.platform_family == 'rhel'", + "parseInt(entity.system.platform_version.split('.')[0]) == 6" + ] + }, + { + "url": "https://assets.bonsai.sensu.io/5123017d3dadf2067fa90fc28275b92e9b586885/sensu-ruby-runtime_0.0.10_ruby-2.4.4_debian_linux_amd64.tar.gz", + "sha512": "a28952fd93fc63db1f8988c7bc40b0ad815eb9f35ef7317d6caf5d77ecfbfd824a9db54184400aa0c81c29b34cb48c7e8c6e3f17891aaf84cafa3c134266a61a", + "filters": [ + "entity.system.os == 'linux'", + "entity.system.arch == 'amd64'", + "entity.system.platform_family == 'debian'" + ] + }, + { + "url": "https://assets.bonsai.sensu.io/5123017d3dadf2067fa90fc28275b92e9b586885/sensu-ruby-runtime_0.0.10_ruby-2.4.4_alpine_linux_amd64.tar.gz", + "sha512": "8d768d1fba545898a8d09dca603457eb0018ec6829bc5f609a1ea51a2be0c4b2d13e1aa46139ecbb04873449e4c76f463f0bdfbaf2107caf37ab1c8db87d5250", + "filters": [ + "entity.system.os == 'linux'", + "entity.system.arch == 'amd64'", + "entity.system.platform == 'alpine'", + "entity.system.platform_version.split('.')[0] == '3'" + ] + } + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +In this example, if you install the dynamic runtime asset on a system running Linux AMD64 Alpine version 3.xx, Sensu will ignore the first two builds and install the third. + +{{% notice note %}} +**NOTE**: Sensu downloads and installs the first build whose filter expressions all evaluate as `true`. +If your system happens to match all of the filters for more than one build of a dynamic runtime asset, Sensu will only install the first build. +{{% /notice %}} + +All of the dynamic runtime asset filter expressions must evaluate as true for Sensu to download and install the asset and run the check, handler, or filter that references the asset. + +To continue this example, if you try to install the dynamic runtime asset on a system running Linux AMD64 Alpine version 2.xx, the `entity.system.platform_version` argument will evaluate as `false`. +In this case, the asset will not be downloaded and the check, handler, or filter that references the asset will fail to run. + +Add dynamic runtime asset filters to specify that an asset is compiled for any of the [entity.system attributes][10], including operating system, platform, platform version, and architecture. +Then, you can rely on dynamic runtime asset filters to ensure that you install only the appropriate asset for each of your agents. + +## Share an asset on Bonsai + +Share your open-source dynamic runtime assets on [Bonsai][16] and connect with the Sensu community. +Bonsai supports dynamic runtime assets hosted on [GitHub][24] and released using [GitHub releases][25]. +For more information about creating Sensu plugins, read the [plugins reference][29]. + +Bonsai requires a [`bonsai.yml` configuration file][26] in the root directory of your repository that includes the project description, platforms, asset filenames, and SHA-512 checksums. +For a Bonsai-compatible dynamic runtime asset template using Go and [GoReleaser][27], review the [Sensu Go plugin skeleton][28]. + +To share your dynamic runtime asset on Bonsai, [log in to Bonsai][37] with your GitHub account and authorize Sensu. +After you are logged in, you can [register your dynamic runtime asset on Bonsai][38] by adding the GitHub repository, a description, and tags. +Make sure to provide a helpful README for your dynamic runtime asset with configuration examples. + +### `bonsai.yml` example + +{{< code yml >}} +--- +description: "#{repo}" +builds: +- platform: "linux" + arch: "amd64" + asset_filename: "#{repo}_#{version}_linux_amd64.tar.gz" + sha_filename: "#{repo}_#{version}_sha512-checksums.txt" + filter: + - "entity.system.os == 'linux'" + - "entity.system.arch == 'amd64'" + +- platform: "Windows" + arch: "amd64" + asset_filename: "#{repo}_#{version}_windows_amd64.tar.gz" + sha_filename: "#{repo}_#{version}_sha512-checksums.txt" + filter: + - "entity.system.os == 'windows'" + - "entity.system.arch == 'amd64'" +{{< /code >}} + +### `bonsai.yml` specification + + description | +-------------|------ +description | Project description. +required | true +type | String +example | {{< code yml >}}description: "#{repo}"{{< /code >}} + + builds | +-------------|------ +description | Array of dynamic runtime asset details per platform. +required | true +type | Array +example | {{< code yml >}} +builds: +- platform: "linux" + arch: "amd64" + asset_filename: "#{repo}_#{version}_linux_amd64.tar.gz" + sha_filename: "#{repo}_#{version}_sha512-checksums.txt" + filter: + - "entity.system.os == 'linux'" + - "entity.system.arch == 'amd64'" +{{< /code >}} + +### Builds specification + + platform | +-------------|------ +description | Platform supported by the dynamic runtime asset. +required | true +type | String +example | {{< code yml >}}- platform: "linux"{{< /code >}} + + arch | +-------------|------ +description | Architecture supported by the dynamic runtime asset. +required | true +type | String +example | {{< code yml >}} arch: "amd64"{{< /code >}} + +asset_filename | +-------------|------ +description | File name of the archive that contains the dynamic runtime asset. +required | true +type | String +example | {{< code yml >}}asset_filename: "#{repo}_#{version}_linux_amd64.tar.gz"{{< /code >}} + +sha_filename | +-------------|------ +description | SHA-512 checksum for the dynamic runtime asset archive. +required | true +type | String +example | {{< code yml >}}sha_filename: "#{repo}_#{version}_sha512-checksums.txt"{{< /code >}} + + filter | +-------------|------ +description | Filter expressions that describe the operating system and architecture supported by the asset. +required | false +type | Array +example | {{< code yml >}} + filter: + - "entity.system.os == 'linux'" + - "entity.system.arch == 'amd64'" +{{< /code >}} + +## Delete dynamic runtime assets + +Delete dynamic runtime assets with a DELETE request to the [`/assets` API endpoint][47] or with the [`sensuctl asset delete` command][48]. + +Removing a dynamic runtime asset from Sensu *does not* remove references to the deleted asset in any other resource (including checks, filters, mutators, handlers, and hooks). +You must also update resources and remove any reference to the deleted dynamic runtime asset. +Failure to do so will result in errors like `sh: asset.sh: command not found`. + +Errors as a result of failing to remove the dynamic runtime asset from checks and hooks will surface in the event data. +Errors as a result of failing to remove the dynamic runtime asset reference on a mutator, handler, or filter will only surface in the backend logs. + +Deleting a dynamic runtime asset does not delete the archive or downloaded files on disk. +You must remove the archive and downloaded files from the asset cache manually. + + +[1]: ../../observability-pipeline/observe-filter/sensu-query-expressions/ +[2]: ../../operations/control-access/namespaces/ +[3]: ../../observability-pipeline/observe-schedule/tokens/#manage-dynamic-runtime-assets +[4]: https://bonsai.sensu.io/assets/sensu/sensu-windows-powershell-checks +[5]: #metadata-attributes +[6]: ../../observability-pipeline/observe-schedule/checks/ +[7]: ../../observability-pipeline/observe-filter/filters/ +[8]: ../../observability-pipeline/observe-transform/mutators/ +[9]: ../../observability-pipeline/observe-process/handlers/ +[10]: ../../observability-pipeline/observe-entities/entities#system-attributes +[11]: ../../sensuctl/create-manage-resources/#create-resources +[12]: #spec-attributes +[13]: https://github.com/sensu/sensu/issues/1919 +[14]: #environment-variables-for-dynamic-runtime-asset-paths +[15]: #example-dynamic-runtime-asset-structure +[16]: https://bonsai.sensu.io/ +[17]: #assetpath-function-for-dynamic-runtime-asset-paths +[18]: https://discourse.sensu.io/t/the-hello-world-of-sensu-assets/1422 +[19]: https://regex101.com/r/zo9mQU/2 +[20]: ../../api/#response-filtering +[21]: ../../sensuctl/filter-responses/ +[22]: https://bonsai.sensu.io/assets/sensu/http-checks +[23]: ../use-assets-to-install-plugins/ +[24]: https://github.com +[25]: https://help.github.com/articles/about-releases/ +[26]: #bonsaiyml-example +[27]: https://goreleaser.com/ +[28]: https://github.com/sensu/sensu-go-plugin/ +[29]: ../plugins/ +[30]: ../../observability-pipeline/observe-schedule/agent#disable-assets +[31]: ../../platforms/#docker-images +[32]: ../../platforms/#supported-packages +[33]: ../../catalog/sensu-catalog/ +[37]: https://bonsai.sensu.io/sign-in +[38]: https://bonsai.sensu.io/new +[39]: ../../web-ui/search#search-for-labels +[40]: ../../observability-pipeline/observe-schedule/agent/#assets-burst-limit +[41]: ../../observability-pipeline/observe-schedule/backend/#backend-configuration-options +[42]: #filters-attribute +[43]: https://bonsai.sensu.io/assets/sensu/sensu-ruby-runtime +[44]: https://devblogs.microsoft.com/oldnewthing/20060823-00/?p=29993 +[45]: https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_environment_variables?view=powershell-7.1 +[46]: https://bonsai.sensu.io/assets/sensu/check-cpu-usage +[47]: ../../api/core/assets/ +[48]: ../../sensuctl/create-manage-resources/#delete-resources diff --git a/content/sensu-go/6.12/plugins/featured-integrations/_index.md b/content/sensu-go/6.12/plugins/featured-integrations/_index.md new file mode 100644 index 0000000000..9caff6ca27 --- /dev/null +++ b/content/sensu-go/6.12/plugins/featured-integrations/_index.md @@ -0,0 +1,75 @@ +--- +title: "Featured Integrations" +description: "Use Sensu plugins to integrate Sensu with your existing workflows for Sumo Logic, PagerDuty, Ansible, Chef, Jira, Elasticsearch, InfluxDB, and more." +product: "Sensu Go" +version: "6.12" +weight: 100 +layout: "single" +toc: true +menu: + sensu-go-6.12: + parent: plugins + identifier: featured-integrations +--- + +Sensu integrations include plugins, libraries, and runtimes that extend Sensu's functionality and allow you to automate your monitoring and observability workflows. +You can also rely on Sensu's integrations to get work done with Sensu as part of your existing workflows. + +Integrations are service-specific and have different setup and configuration requirements. +Each integration has self-contained documentation with in-depth information about how to install and use it. +Many of the featured integrations include curated quick-start templates that you only need to edit to match your configuration. + +Although this category focuses on our most popular featured integrations, you can find more supported-, Enterprise-, and community-tier integrations at [Bonsai, the Sensu asset hub][1]. + +## Alerting and incident management + +- [Email][3] +- [Jira][4] +- [PagerDuty][5] +- [ServiceNow][6] +- [Slack][7] + +## Auto-remediation + +- [Ansible][8] +- [Rundeck][9] +- [SaltStack][10] + +## Deregistration + +- [Chef][11] +- [EC2][2] +- [Puppet][12] + +## Time-series and long-term event storage + +- [Elasticsearch][13] +- [Graphite][15] +- [InfluxDB][14] +- [OpenTSDB][16] +- [Prometheus][17] +- [Sumo Logic][20] +- [TimescaleDB][18] +- [Wavefront][19] + + +[1]: https://bonsai.sensu.io/ +[2]: aws-ec2/ +[3]: email/ +[4]: jira/ +[5]: pagerduty/ +[6]: servicenow/ +[7]: slack/ +[8]: ansible/ +[9]: rundeck/ +[10]: saltstack/ +[11]: chef/ +[12]: puppet/ +[13]: elasticsearch/ +[14]: influxdb/ +[15]: graphite/ +[16]: opentsdb/ +[17]: prometheus/ +[18]: timescaledb/ +[19]: wavefront/ +[20]: sumologic/ diff --git a/content/sensu-go/6.12/plugins/featured-integrations/ansible.md b/content/sensu-go/6.12/plugins/featured-integrations/ansible.md new file mode 100644 index 0000000000..80e394d41f --- /dev/null +++ b/content/sensu-go/6.12/plugins/featured-integrations/ansible.md @@ -0,0 +1,55 @@ +--- +title: "Ansible integration" +linkTitle: "Ansible" +description: "Use the Sensu Ansible Handler integration to launch Ansible Tower job templates for automated remediation based on Sensu observability event data." +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: featured-integrations +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access the Sensu Ansible Handler integration in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} + +The Sensu Ansible Handler plugin is a Sensu [handler][1] that launches Ansible Tower job templates for automated remediation based on Sensu observability event data. + +{{% notice protip %}} +**PRO TIP**: Use the [Sensu Catalog](../../../catalog/sensu-catalog/) to enable this integration directly from your browser. +Follow the Catalog prompts to configure the Sensu resources you need and start processing your observability data with a few clicks. +{{% /notice %}} + +## Features + +The [Sensu Ansible Handler plugin][4] supports both Ansible Tower and Ansible AWX implementations of the Ansible Tower API, authenticating using Ansible Tower API tokens. + +- Specify a default Ansible Tower job template for remediation actions for all checks and use check annotations to override the default as needed on a check-by check-basis. +- Automatically limit Ansible jobs to the host that matches the Sensu entity name encoded in a Sensu event. +- Optional job template requests: use Sensu check annotations to specify a set of Ansible Tower job template requests to run for matching Sensu event occurrence and severity conditions. +- Keep your Ansible Tower host and auth token secure with Sensu [environment variables and secrets management][9]. + +## Get the plugin + +For a turnkey experience with the Sensu Ansible Handler plugin, use the [Sensu Catalog][10] in the web UI to configure and install it. +Or, use our curated, configurable [quick-start template][3] to integrate Sensu with your existing Ansible Tower workflows. + +You can also add the [Sensu Ansible Handler plugin][4] with a dynamic runtime asset from Bonsai, the Sensu asset hub, to build your own workflow or integrate Sensu with your existing Ansible workflows. +[Dynamic runtime assets][5] are shareable, reusable packages that make it easier to deploy Sensu plugins. + +## Configuration management + +Use the official [Sensu Go Ansible Collection][7] for configuration management for your Sensu instance. +The [documentation site][8] includes installation instructions, example playbooks, and module references + + +[1]: ../../../observability-pipeline/observe-process/handlers/ +[2]: ../../../observability-pipeline/observe-process/handler-templates/ +[3]: https://github.com/sensu/catalog/blob/docs-archive/integrations/ansible/ansible-tower-handler.yaml +[4]: https://bonsai.sensu.io/assets/sensu/sensu-ansible-handler +[5]: ../../assets/ +[7]: https://galaxy.ansible.com/sensu/sensu_go +[8]: https://sensu.github.io/sensu-go-ansible/ +[9]: ../../../operations/manage-secrets/ +[10]: ../../../catalog/sensu-catalog/ diff --git a/content/sensu-go/6.12/plugins/featured-integrations/aws-ec2.md b/content/sensu-go/6.12/plugins/featured-integrations/aws-ec2.md new file mode 100644 index 0000000000..b7de3459a7 --- /dev/null +++ b/content/sensu-go/6.12/plugins/featured-integrations/aws-ec2.md @@ -0,0 +1,45 @@ +--- +title: "EC2 integration" +linkTitle: "EC2" +description: "Use the Sensu EC2 Handler integration to set custom values in EC2 based on Sensu Go observability event data and protect your EC2 authentication details." +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: featured-integrations +--- + +The [Sensu EC2 Handler plugin][4] is a Sensu [handler][1] that checks an AWS EC2 instance and removes it from Sensu if it is not in one of the specified states. + +{{% notice note %}} +**NOTE**: The Sensu EC2 Handler plugin is an example of Sensu's deregistration integrations. +To find more integrations, search [Bonsai, the Sensu asset hub](https://bonsai.sensu.io/). +{{% /notice %}} + +## Features + +- Tunable arguments: use Sensu annotations to set custom instance ID, instance ID labels, timeouts, and more in EC2. +- Specify custom values for Sensu event metric points via [metric tags][7]. +- Keep your AWS EC2 API token, username, and password secure with Sensu [environment variables and secrets management][3]. + +## Get the plugin + +For a turnkey experience with the Sensu EC2 Handler plugin, use our curated, configurable [quick-start template][8] to integrate Sensu with your existing AWS EC2 workflows. + +You can also add the [Sensu EC2 Handler plugin][4] with a dynamic runtime asset from Bonsai, the Sensu asset hub, to build your own workflow or integrate Sensu with your existing EC2 workflows. +[Dynamic runtime assets][5] are shareable, reusable packages that make it easier to deploy Sensu plugins. + +## More resources + +Set up a [limited service account][9] with the access and permissions required to automatically remove AWS EC2 instances using the Sensu EC2 Handler integration. + + +[1]: ../../../observability-pipeline/observe-process/handlers/ +[2]: ../../../observability-pipeline/observe-process/handler-templates/ +[3]: ../../../operations/manage-secrets/ +[4]: https://bonsai.sensu.io/assets/sensu/sensu-ec2-handler +[5]: ../../assets +[6]: ../../../commercial/ +[7]: ../../../observability-pipeline/observe-schedule/checks/#output-metric-tags +[8]: https://github.com/sensu/catalog/blob/docs-archive/integrations/aws/aws-ec2-deregistration.yaml +[9]: ../../../operations/control-access/create-limited-service-accounts/ diff --git a/content/sensu-go/6.12/plugins/featured-integrations/chef.md b/content/sensu-go/6.12/plugins/featured-integrations/chef.md new file mode 100644 index 0000000000..789ca8451e --- /dev/null +++ b/content/sensu-go/6.12/plugins/featured-integrations/chef.md @@ -0,0 +1,39 @@ +--- +title: "Chef integration" +linkTitle: "Chef" +description: "Use the Sensu Chef Handler integration to delete a Sensu entity with a failing keepalive check when the entity's corresponding Chef node no longer exists." +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: featured-integrations +--- + +The [Sensu Chef Handler plugin][4] is a Sensu [handler][1] that deletes a Sensu entity with a failing keepalive check when the entity's corresponding Chef node no longer exists. + +{{% notice note %}} +**NOTE**: The Sensu Chef Handler plugin is an example of Sensu's deregistration integrations. +To find more integrations, search [Bonsai, the Sensu asset hub](https://bonsai.sensu.io/). +{{% /notice %}} + +## Features + +- Use Sensu annotations to override Sensu entity names with corresponding Chef node names. +- Keep your sensitive API authentication information secure with Sensu [environment variables and secrets management][6]. + +## Get the plugin + +Add the [Sensu Chef Handler plugin][4] with a dynamic runtime asset from Bonsai, the Sensu asset hub, to build your own workflow or integrate Sensu with your existing Chef workflows. +[Dynamic runtime assets][5] are shareable, reusable packages that make it easier to deploy Sensu plugins. + +## Configuration management + +Use the official [Chef Cookbook for Sensu Go][3] for configuration management for your Sensu instance. + + +[1]: ../../../observability-pipeline/observe-process/handlers/ +[2]: ../../../observability-pipeline/observe-process/handler-templates/ +[3]: https://supermarket.chef.io/cookbooks/sensu-go +[4]: https://bonsai.sensu.io/assets/sensu/sensu-chef-handler +[5]: ../../assets +[6]: ../../../operations/manage-secrets/ diff --git a/content/sensu-go/6.12/plugins/featured-integrations/elasticsearch.md b/content/sensu-go/6.12/plugins/featured-integrations/elasticsearch.md new file mode 100644 index 0000000000..a10ee30215 --- /dev/null +++ b/content/sensu-go/6.12/plugins/featured-integrations/elasticsearch.md @@ -0,0 +1,51 @@ +--- +title: "Elasticsearch integration" +linkTitle: "Elasticsearch" +description: "Use the Sensu Elasticsearch Handler integration to send observation data from Sensu events to Elasticsearch for indexing and visualization in Kibana." +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: featured-integrations +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access the Sensu Elasticsearch Handler integration in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} + +The [Sensu Elasticsearch Handler plugin][4] is a Sensu [handler][1] that sends observation data from Sensu events and metrics to Elasticsearch. +With this handler, the Sensu observation data you send to Elasticsearch is available for indexing and visualization in Kibana. + +{{% notice protip %}} +**PRO TIP**: Use the [Sensu Catalog](../../../catalog/sensu-catalog/) to enable this integration directly from your browser. +Follow the Catalog prompts to configure the Sensu resources you need and start processing your observability data with a few clicks. +{{% /notice %}} + +## Features + +- Query metrics points within Elasticsearch: the handler automatically mutates metrics data by creating a top-level object with metric point names and their associated values. +- Index entire events for searching within Kibana. +- Use daily, weekly, monthly, and yearly index specification (for example, sensu_events-2020-11-10). +- Omit the transmission of certain redundant event fields to reduce the number of items indexed. +- Specify custom values for Sensu event metric points via [metric tags][8]. +- Use [event-based templating][2] to include observation data from event attributes to add meaningful, actionable context. +- Keep your Elasticsearch username and password secure with Sensu [environment variables and secrets management][7]. + +## Get the plugin + +For a turnkey experience with the Sensu Elasticsearch Handler plugin, use the [Sensu Catalog][10] in the web UI to configure and install it. +Or, use our curated, configurable [quick-start template][3] for events and metrics data storage. + +You can also add the [Sensu Elasticsearch Handler plugin][4] with a dynamic runtime asset from Bonsai, the Sensu asset hub, to build your own workflow or integrate Sensu with your existing Elasticsearch workflows. +[Dynamic runtime assets][5] are shareable, reusable packages that make it easier to deploy Sensu plugins. + + +[1]: ../../../observability-pipeline/observe-process/handlers/ +[2]: ../../../observability-pipeline/observe-process/handler-templates/ +[3]: https://github.com/sensu/catalog/blob/docs-archive/integrations/elasticsearch/elasticsearch.yaml +[4]: https://bonsai.sensu.io/assets/sensu/sensu-elasticsearch-handler +[5]: ../../assets/ +[7]: ../../../operations/manage-secrets/ +[8]: ../../../observability-pipeline/observe-schedule/checks/#output-metric-tags +[10]: ../../../catalog/sensu-catalog/ diff --git a/content/sensu-go/6.12/plugins/featured-integrations/email.md b/content/sensu-go/6.12/plugins/featured-integrations/email.md new file mode 100644 index 0000000000..8dbd4acc17 --- /dev/null +++ b/content/sensu-go/6.12/plugins/featured-integrations/email.md @@ -0,0 +1,47 @@ +--- +title: "Email integration" +linkTitle: "Email" +description: "Use the Sensu Email Handler integration to send messages to the email addresses you specify based on Sensu observability event data." +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: featured-integrations +--- + +The [Sensu Email Handler plugin][4] is a Sensu [handler][1] that sends email alerts based on your event data. +With this handler, Sensu can send email messages to the email addresses you specify based on event data generated by your Sensu checks. + +{{% notice protip %}} +**PRO TIP**: Use the [Sensu Catalog](../../../catalog/sensu-catalog/) to enable this integration directly from your browser. +Follow the Catalog prompts to configure the Sensu resources you need and start processing your observability data with a few clicks. +{{% /notice %}} + +## Features + +The [Sensu Email Handler plugin][4] supports the login authentication mechanisms required for use with Google Mail, Office 365, and other standards-based email providers and transports. + +- Use [event-based templating][2] to include observation data from event attributes to add meaningful, actionable context to your email alert messages. +- Keep your email provider username and password secure with Sensu [environment variables and secrets management][7]. + +## Get the plugin + +For a turnkey experience with the Sensu Email Handler plugin, use the [Sensu Catalog][10] in the web UI to configure and install it. +Or, use our curated, configurable [quick-start template][8] to integrate Sensu with your existing workflows and send email alerts. + +You can also add the [Sensu Email Handler plugin][4] with a dynamic runtime asset from Bonsai, the Sensu asset hub, to build your own workflow or integrate Sensu with your existing email workflows. +[Dynamic runtime assets][5] are shareable, reusable packages that make it easier to deploy Sensu plugins. + +## More resources + +Walk through adding and configuring the Sensu Email Handler asset in the [Send email alerts with the Sensu Go Email Handler][3] guide. + + +[1]: ../../../observability-pipeline/observe-process/handlers/ +[2]: ../../../observability-pipeline/observe-process/handler-templates/ +[3]: ../../../observability-pipeline/observe-process/send-email-alerts/ +[4]: https://bonsai.sensu.io/assets/sensu/sensu-email-handler +[5]: ../../assets/ +[7]: ../../../operations/manage-secrets/ +[8]: https://github.com/sensu/catalog/blob/docs-archive/integrations/email/email.yaml +[10]: ../../../catalog/sensu-catalog/ diff --git a/content/sensu-go/6.12/plugins/featured-integrations/graphite.md b/content/sensu-go/6.12/plugins/featured-integrations/graphite.md new file mode 100644 index 0000000000..b302c68f40 --- /dev/null +++ b/content/sensu-go/6.12/plugins/featured-integrations/graphite.md @@ -0,0 +1,38 @@ +--- +title: "Graphite integration" +linkTitle: "Graphite" +description: "Use the Sensu Graphite Handler integration to send Sensu metrics to the time-series database Graphite so you can store, instrument, and visualize Sensu data." +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: featured-integrations +--- + +The [Sensu Graphite Handler plugin][2] is a Sensu [handler][1] that sends Sensu metrics to the time-series database Graphite so you can store, instrument, and visualize Sensu metrics data. + +{{% notice note %}} +**NOTE**: The Sensu Graphite Handler plugin is an example of Sensu's time-series and long-term event storage integrations. +To find more integrations, search [Bonsai, the Sensu asset hub](https://bonsai.sensu.io/). +{{% /notice %}} + +## Features + +- Transform metrics to Graphite format: extract and transform the metrics you collect from different sources in formats like Influx, Nagios, and OpenTSDB and populate them into Graphite. +- Specify custom values for Sensu event metric points via [metric tags][4]. +- Keep your Graphite host and port secure with Sensu [environment variables and secrets management][6]. + +## Get the plugin + +For a turnkey experience with the Sensu Graphite Handler plugin, use our curated, configurable [quick-start template][5] to integrate Sensu with your existing workflows and store Sensu metrics in Graphite. + +To build your own workflow or integrate Sensu with existing workflows, add the [Sensu Graphite Handler plugin][2] with a dynamic runtime asset from Bonsai, the Sensu asset hub. +[Dynamic runtime assets][3] are shareable, reusable packages that make it easier to deploy Sensu plugins. + + +[1]: ../../../observability-pipeline/observe-process/handlers/ +[2]: https://bonsai.sensu.io/assets/sensu/sensu-go-graphite-handler +[3]: ../../assets/ +[4]: ../../../observability-pipeline/observe-schedule/checks/#output-metric-tags +[5]: https://github.com/sensu/catalog/blob/docs-archive/integrations/graphite/graphite.yaml +[6]: ../../../operations/manage-secrets/ diff --git a/content/sensu-go/6.12/plugins/featured-integrations/influxdb.md b/content/sensu-go/6.12/plugins/featured-integrations/influxdb.md new file mode 100644 index 0000000000..03babbc65d --- /dev/null +++ b/content/sensu-go/6.12/plugins/featured-integrations/influxdb.md @@ -0,0 +1,43 @@ +--- +title: "InfluxDB integration" +linkTitle: "InfluxDB" +description: "Integrate Sensu with your existing InfluxDB workflows and send Sensu metrics to InfluxDB for storage, instrumentation, and visualization." +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: featured-integrations +--- + +The [Sensu InfluxDB Handler plugin][4] is a Sensu [handler][1] that sends Sensu metrics to the time-series database InfluxDB so you can store, instrument, and visualize Sensu metrics data. +You can also use the Sensu InfluxDB Handler integration to create metrics from Sensu status check results for long-term storage in InfluxDB. + +{{% notice protip %}} +**PRO TIP**: Use the [Sensu Catalog](../../../catalog/sensu-catalog/) to enable this integration directly from your browser. +Follow the Catalog prompts to configure the Sensu resources you need and start processing your observability data with a few clicks. +{{% /notice %}} + +## Features + +- Transform metrics to InfluxDB format: extract and transform the metrics you collect from different sources in formats like Graphite, OpenTSDB, Nagios, and Influx and populate them into InfluxDB. +- Mutate check status into metrics to be stored in InfluxDB. +- Specify custom values for Sensu event metric points via [metric tags][7]. +- Keep your InfluxDB username and password secure with Sensu [environment variables and secrets management][6]. + +## Get the plugin + +For a turnkey experience with the Sensu InfluxDB Handler plugin, use the [Sensu Catalog][10] in the web UI to configure and install it. +Or, use our curated, configurable [quick-start template][3] to integrate Sensu with your existing workflows and store Sensu metrics in InfluxDB. + +To build your own workflow or integrate Sensu with existing workflows, add the [Sensu InfluxDB Handler plugin][4] with a dynamic runtime asset from Bonsai, the Sensu asset hub. +[Dynamic runtime assets][5] are shareable, reusable packages that make it easier to deploy Sensu plugins. + + +[1]: ../../../observability-pipeline/observe-process/handlers/ +[2]: ../../../observability-pipeline/observe-process/handler-templates/ +[3]: https://github.com/sensu/catalog/blob/docs-archive/integrations/influxdb/influxdb.yaml +[4]: https://bonsai.sensu.io/assets/sensu/sensu-influxdb-handler +[5]: ../../assets/ +[6]: ../../../operations/manage-secrets/ +[7]: ../../../observability-pipeline/observe-schedule/checks/#output-metric-tags +[10]: ../../../catalog/sensu-catalog/ diff --git a/content/sensu-go/6.12/plugins/featured-integrations/jira.md b/content/sensu-go/6.12/plugins/featured-integrations/jira.md new file mode 100644 index 0000000000..119fd688f1 --- /dev/null +++ b/content/sensu-go/6.12/plugins/featured-integrations/jira.md @@ -0,0 +1,43 @@ +--- +title: "Jira integration" +linkTitle: "Jira" +description: "Use the Sensu Jira Handler integration to create and update Jira issues based on data from Sensu observability events." +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: featured-integrations +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access the Sensu Jira Handler integration in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} + +The [Sensu Jira Handler plugin][4] is a Sensu [handler][1] that creates and updates Jira issues based on observation data from Sensu events. + +{{% notice protip %}} +**PRO TIP**: Use the [Sensu Catalog](../../../catalog/sensu-catalog/) to enable this integration directly from your browser. +Follow the Catalog prompts to configure the Sensu resources you need and start processing your observability data with a few clicks. +{{% /notice %}} + +## Features + +- Tunable arguments: use Sensu annotations to set custom project names, issue types, resolution states, and more in Jira +- Use [event-based templating][2] to include observation data from event attributes to add meaningful, actionable context. +- Keep your Jira username, password, and API token secure with Sensu [environment variables and secrets management][7]. + +## Get the plugin + +For a turnkey experience with the Sensu Jira Handler plugin, use our curated, configurable [quick-start template][3] to send alerts based on Sensu events to Jira Service Desk. + +Add the [Sensu Jira Handler plugin][4] with a dynamic runtime asset from Bonsai, the Sensu asset hub, to build your own workflow or integrate Sensu with your existing Jira workflows. +[Dynamic runtime assets][5] are shareable, reusable packages that make it easier to deploy Sensu plugins. + + +[1]: ../../../observability-pipeline/observe-process/handlers/ +[2]: ../../../observability-pipeline/observe-process/handler-templates/ +[3]: https://github.com/sensu/catalog/blob/docs-archive/integrations/jira/jira-servicedesk.yaml +[4]: https://bonsai.sensu.io/assets/sensu/sensu-jira-handler +[5]: ../../assets/ +[7]: ../../../operations/manage-secrets/ diff --git a/content/sensu-go/6.12/plugins/featured-integrations/opentsdb.md b/content/sensu-go/6.12/plugins/featured-integrations/opentsdb.md new file mode 100644 index 0000000000..5a3c29f099 --- /dev/null +++ b/content/sensu-go/6.12/plugins/featured-integrations/opentsdb.md @@ -0,0 +1,36 @@ +--- +title: "OpenTSDB integration" +linkTitle: "OpenTSDB" +description: "Use the Sensu OpenTSDB Handler integration to send Sensu metrics to an OpenTSDB server so you can extract, tag, and store Sensu data in an OpenTSDB database." +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: featured-integrations +--- + +The [Sensu OpenTSDB Handler plugin][4] is a Sensu [handler][1] that sends Sensu metrics to an OpenTSDB server via its Telnet-style API. +This allows you to extract, tag, and store Sensu metrics data in an OpenTSDB database. + +{{% notice note %}} +**NOTE**: The Sensu OpenTSDB Handler plugin is an example of Sensu's time-series and long-term event storage integrations. +To find more integrations, search [Bonsai, the Sensu asset hub](https://bonsai.sensu.io/). +{{% /notice %}} + +## Features + +- Transform metrics to OpenTSDB format: extract and transform the metrics you collect from different sources in formats like Graphite, Influx, and Nagios and populate them into OpenTSDB. +- Specify custom values for Sensu event metric points via [metric tags][6]. + +## Get the plugin + +To build your own workflow or integrate Sensu with existing workflows, add the [Sensu OpenTSDB Handler plugin][4] with a dynamic runtime asset from Bonsai, the Sensu asset hub. +[Dynamic runtime assets][5] are shareable, reusable packages that make it easier to deploy Sensu plugins. + + +[1]: ../../../observability-pipeline/observe-process/handlers/ +[2]: ../../../observability-pipeline/observe-process/handler-templates/ +[3]: ../../../operations/manage-secrets/ +[4]: https://bonsai.sensu.io/assets/sensu/sensu-opentsdb-handler +[5]: ../../assets/ +[6]: ../../../observability-pipeline/observe-schedule/checks/#output-metric-tags diff --git a/content/sensu-go/6.12/plugins/featured-integrations/pagerduty.md b/content/sensu-go/6.12/plugins/featured-integrations/pagerduty.md new file mode 100644 index 0000000000..2f8037c1d5 --- /dev/null +++ b/content/sensu-go/6.12/plugins/featured-integrations/pagerduty.md @@ -0,0 +1,49 @@ +--- +title: "PagerDuty integration" +linkTitle: "PagerDuty" +description: "Use the Sensu PagerDuty Handler integration to automate incident management and operator alerts and integrate Sensu with your existing PagerDuty workflows." +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: featured-integrations +--- + +The [Sensu PagerDuty Handler plugin][4] is a Sensu [handler][1] that manages PagerDuty incidents and operator alerts. +With this handler, Sensu can trigger and resolve PagerDuty incidents according to the PagerDuty schedules, notifications, and escalation, response, and orchestration workflows you already have configured. + +{{% notice protip %}} +**PRO TIP**: Use the [Sensu Catalog](../../../catalog/sensu-catalog/) to enable this integration directly from your browser. +Follow the Catalog prompts to configure the Sensu resources you need and start processing your observability data with a few clicks. +{{% /notice %}} + +## Features + +- Optional severity mapping: match Sensu check statuses with PagerDuty incident severities via a JSON document. +- Use [event-based templating][2] to create deduplication key arguments to group repeated alerts into one incident and summary template arguments to make sure your PagerDuty notifications include the event data your operators need to take action. +- Authenticate and route alerts based on PagerDuty teams using check and agent annotations. +- Keep your PagerDuty integration key secure with Sensu [environment variables and secrets management][8]. + +## Get the plugin + +For a turnkey experience with the Sensu PagerDuty Handler plugin, use the [Sensu Catalog][10] in the web UI to configure and install it. +Or, use our curated, configurable [quick-start template][3] for incident management to integrate Sensu with your existing PagerDuty workflows. + +To build your own workflow or integrate Sensu with existing workflows, add the [Sensu PagerDuty Handler plugin][4] with a dynamic runtime asset from Bonsai, the Sensu asset hub. +[Dynamic runtime assets][5] are shareable, reusable packages that make it easier to deploy Sensu plugins. + +## More resources + +- Follow the [Use dynamic runtime assets to install plugins][6] guide to learn how to add and configure Sensu PagerDuty Handler asset. +- Demo the Sensu PagerDuty Handler integration with the [Send Sensu Go alerts to PagerDuty][7] guide. + + +[1]: ../../../observability-pipeline/observe-process/handlers/ +[2]: ../../../observability-pipeline/observe-process/handler-templates/ +[3]: https://github.com/sensu/catalog/blob/docs-archive/integrations/pagerduty/pagerduty-handler.yaml +[4]: https://bonsai.sensu.io/assets/sensu/sensu-pagerduty-handler +[5]: ../../assets/ +[6]: ../../use-assets-to-install-plugins/ +[7]: ../../../observability-pipeline/observe-process/send-pagerduty-alerts/ +[8]: ../../../operations/manage-secrets/ +[10]: ../../../catalog/sensu-catalog/ diff --git a/content/sensu-go/6.12/plugins/featured-integrations/prometheus.md b/content/sensu-go/6.12/plugins/featured-integrations/prometheus.md new file mode 100644 index 0000000000..83c8f91c67 --- /dev/null +++ b/content/sensu-go/6.12/plugins/featured-integrations/prometheus.md @@ -0,0 +1,60 @@ +--- +title: "Prometheus integrations" +linkTitle: "Prometheus" +description: "Use Sensu's Prometheus Collector and Prometheus Pushgateway Handler to send data to Prometheus and integrate Sensu with your existing Prometheus workflows." +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: featured-integrations +--- + +Sensu has two Prometheus plugins: the [Prometheus Collector][3] and the [Prometheus Pushgateway Handler][4]. +Both help you get Sensu observability data into Prometheus. + +{{% notice note %}} +**NOTE**: The Sensu Prometheus plugins are examples of Sensu's time-series and long-term event storage integrations. +To find more integrations, search [Bonsai, the Sensu asset hub](https://bonsai.sensu.io/). +{{% /notice %}} + +## Sensu Prometheus Collector + +The [Sensu Prometheus Collector plugin][6] is a Sensu [check][8] that collects metrics from a Prometheus exporter or the Prometheus query API and outputs the metrics to stdout in Influx, Graphite, or JSON format. + +### Features + +- Turn Sensu into a super-powered Prometheus metric poller with Sensu's [publish/subscribe model][9] and [client auto-registration (discovery)][10] capabilities. +- Configure your Sensu instance to deliver the collected metrics to a time-series database like InfluxDB or Graphite. +- Specify custom values for Sensu event metric points via [metric tags][12]. +- Keep metrics endpoint authentication information secure with Sensu [environment variables and secrets management][11]. + +## Sensu Prometheus Pushgateway Handler + +The [Sensu Prometheus Pushgateway Handler][7] plugin is a Sensu [handler][1] that sends Sensu metrics to a Prometheus Pushgateway, which Prometheus can then scrape. + +### Features + +- Collect metrics by several means, including 20-year-old Nagios plugins with perfdata, and store them in Prometheus. +- Use default Prometheus metric type, job name, and instance name or specify custom values for Sensu event metric points via [metric tags][12]. + +## Get the plugins + +To build your own workflow or integrate Sensu with existing workflows, add the Sensu Prometheus plugins with a dynamic runtime asset from Bonsai, the Sensu asset hub. +[Dynamic runtime assets][5] are shareable, reusable packages that make it easier to deploy Sensu plugins. + +- [Sensu Prometheus Collector plugin][6] +- [Sensu Prometheus Pushgateway Handler][7] + + +[1]: ../../../observability-pipeline/observe-process/handlers/ +[2]: ../../../observability-pipeline/observe-process/handler-templates/ +[3]: #sensu-prometheus-collector +[4]: #sensu-prometheus-pushgateway-handler +[5]: ../../assets/ +[6]: https://bonsai.sensu.io/assets/sensu/sensu-prometheus-collector +[7]: https://bonsai.sensu.io/assets/portertech/sensu-prometheus-pushgateway-handler +[8]: ../../../observability-pipeline/observe-schedule/checks/ +[9]: https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern +[10]: ../../../observability-pipeline/observe-schedule/agent/#registration-endpoint-management-and-service-discovery +[11]: ../../../operations/manage-secrets/ +[12]: ../../../observability-pipeline/observe-schedule/checks/#output-metric-tags diff --git a/content/sensu-go/6.12/plugins/featured-integrations/puppet.md b/content/sensu-go/6.12/plugins/featured-integrations/puppet.md new file mode 100644 index 0000000000..cf6c9cc157 --- /dev/null +++ b/content/sensu-go/6.12/plugins/featured-integrations/puppet.md @@ -0,0 +1,39 @@ +--- +title: "Puppet integration" +linkTitle: "Puppet" +description: "Use the Sensu Puppet Keepalive Handler integration to delete Sensu entities with failing keepalives when matching Puppet nodes don't exist or are deregistered." +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: featured-integrations +--- + +The [Sensu Puppet Keepalive Handler plugin][4] is a Sensu [handler][1] that deletes a Sensu entity with a failing keepalive check when the entity's corresponding Puppet node no longer exists or is deregistered. + +{{% notice note %}} +**NOTE**: The Sensu Puppet Keepalive Handler plugin is an example of Sensu's deregistration integrations. +To find more integrations, search [Bonsai, the Sensu asset hub](https://bonsai.sensu.io/). +{{% /notice %}} + +## Features + +- Use Sensu annotations to override Sensu entity names with corresponding Puppet node names. +- Keep sensitive API authentication information secure with Sensu [environment variables and secrets management][6]. + +## Get the plugin + +Add the [Sensu Puppet Keepalive Handler plugin][4] with a dynamic runtime asset from Bonsai, the Sensu asset hub, to build your own workflow or integrate Sensu with your existing Puppet workflows. +[Dynamic runtime assets][5] are shareable, reusable packages that make it easier to deploy Sensu plugins. + +## Configuration management + +Use the partner-supported [Sensu Puppet module][3] for configuration management for your Sensu instance. + + +[1]: ../../../observability-pipeline/observe-process/handlers/ +[2]: ../../../observability-pipeline/observe-process/handler-templates/ +[3]: https://forge.puppet.com/modules/sensu/sensu +[4]: https://bonsai.sensu.io/assets/sensu/sensu-puppet-handler +[5]: ../../assets +[6]: ../../../operations/manage-secrets/ diff --git a/content/sensu-go/6.12/plugins/featured-integrations/rundeck.md b/content/sensu-go/6.12/plugins/featured-integrations/rundeck.md new file mode 100644 index 0000000000..3a79543cc0 --- /dev/null +++ b/content/sensu-go/6.12/plugins/featured-integrations/rundeck.md @@ -0,0 +1,49 @@ +--- +title: "Rundeck integration" +linkTitle: "Rundeck" +description: "Use the Sensu Rundeck Handler integrate to initiate Rundeck jobs for automated remediation based on Sensu observability event data." +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: featured-integrations +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access the Sensu Rundeck Handler integration in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} + +The [Sensu Rundeck Handler plugin][4] is a Sensu [handler][1] that initiates Rundeck jobs for automated remediation based on Sensu event data. + +{{% notice note %}} +**NOTE**: The Sensu Rundeck Handler plugin is an example of Sensu's auto-remediation integrations. +To find more integrations, search [Bonsai, the Sensu asset hub](https://bonsai.sensu.io/). +{{% /notice %}} + +## Features + +The [Sensu Rundeck Handler plugin][4] supports both Rundeck Enterprise and Rundeck Open Source and standard job invocation or webhook invocation. + +- Specify Rundeck jobs and webhooks along with trigger parameters for remediation actions for a check with Sensu annotations. +- Use [event-based templating][2] to make use of event data to specify the node to target for rememdiation. +- Keep your Rundeck auth token and webhook secure with Sensu [environment variables and secrets management][8]. + +## Get the plugin + +For a turnkey experience with the Sensu Rundeck Handler plugin, use one of our curated, configurable quick-start templates: + +- [Rundeck job][7] +- [Rundeck webhook][3] + +You can also add the [Sensu Rundeck Handler plugin][4] with a dynamic runtime asset from Bonsai, the Sensu asset hub, to build your own workflow or integrate Sensu with your existing Rundeck workflows. +[Dynamic runtime assets][5] are shareable, reusable packages that make it easier to deploy Sensu plugins. + + +[1]: ../../../observability-pipeline/observe-process/handlers/ +[2]: ../../../observability-pipeline/observe-process/handler-templates/ +[3]: https://github.com/sensu/catalog/blob/docs-archive/integrations/rundeck/rundeck-webhook.yaml +[4]: https://bonsai.sensu.io/assets/sensu/sensu-rundeck-handler +[5]: ../../assets/ +[7]: https://github.com/sensu/catalog/blob/docs-archive/integrations/rundeck/rundeck.yaml +[8]: ../../../operations/manage-secrets/ diff --git a/content/sensu-go/6.12/plugins/featured-integrations/saltstack.md b/content/sensu-go/6.12/plugins/featured-integrations/saltstack.md new file mode 100644 index 0000000000..f5af179690 --- /dev/null +++ b/content/sensu-go/6.12/plugins/featured-integrations/saltstack.md @@ -0,0 +1,45 @@ +--- +title: "SaltStack integration" +linkTitle: "SaltStack" +description: "Use the Sensu SaltStack Handler integration to launch SaltStack functions for automated remediation based on Sensu observability event data." +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: featured-integrations +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access the Sensu SaltStack Handler integration in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} + +The [Sensu SaltStack Handler plugin][4] is a Sensu [handler][1] that launches SaltStack functions for automated remediation based on Sensu event data. + +{{% notice protip %}} +**PRO TIP**: Use the [Sensu Catalog](../../../catalog/sensu-catalog/) to enable this integration directly from your browser. +Follow the Catalog prompts to configure the Sensu resources you need and start processing your observability data with a few clicks. +{{% /notice %}} + +## Features + +The [Sensu SaltStack Handler plugin][4] supports both SaltStack Enterprise and SaltStack Open Source as well as SaltStack functions such as `service`, `state`, `saltutil`, and `grains` (including `arg` and `kwarg` arguments). + +- Specify SaltStack functions and trigger parameters for remediation actions for a check with Sensu annotations. +- Use [event-based templating][2] to specify the minion to target for rememdiation based on event data. +- Keep your SaltStack username and password secure with Sensu [environment variables and secrets management][7]. + +## Get the plugin + +For a turnkey experience with the Sensu SaltStack Handler plugin, use our curated, configurable [quick-start template][3] to integrate Sensu with your existing SaltStack workflows. + +You can also add the [Sensu SaltStack Handler plugin][4] with a dynamic runtime asset from Bonsai, the Sensu asset hub, to build your own workflow or integrate Sensu with your existing SaltStack workflows. +[Dynamic runtime assets][5] are shareable, reusable packages that make it easier to deploy Sensu plugins. + + +[1]: ../../../observability-pipeline/observe-process/handlers/ +[2]: ../../../observability-pipeline/observe-process/handler-templates/ +[3]: https://github.com/sensu/catalog/blob/docs-archive/integrations/saltstack/saltstack-handler.yaml +[4]: https://bonsai.sensu.io/assets/sensu/sensu-saltstack-handler +[5]: ../../assets/ +[7]: ../../../operations/manage-secrets/ diff --git a/content/sensu-go/6.12/plugins/featured-integrations/servicenow.md b/content/sensu-go/6.12/plugins/featured-integrations/servicenow.md new file mode 100644 index 0000000000..533d8e8951 --- /dev/null +++ b/content/sensu-go/6.12/plugins/featured-integrations/servicenow.md @@ -0,0 +1,50 @@ +--- +title: "ServiceNow integration" +linkTitle: "ServiceNow" +description: "Use the Sensu ServiceNow Handler integration to create and update ServiceNow incidents and events based on observation data from Sensu Go events." +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: featured-integrations +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access the Sensu ServiceNow Handler integration in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../../commercial/). +{{% /notice %}} + +The [Sensu ServiceNow Handler plugin][4] is a Sensu [handler][1] that creates and updates ServiceNow incidents and events based on observation data from Sensu events. + +{{% notice protip %}} +**PRO TIP**: Use the [Sensu Catalog](../../../catalog/sensu-catalog/) to enable this integration directly from your browser. +Follow the Catalog prompts to configure the Sensu resources you need and start processing your observability data with a few clicks. +{{% /notice %}} + +## Features + +- Automatically create a ServiceNow Configuration Item if none currently exists for a particular Sensu entity. +- Tunable arguments: use Sensu annotations to set custom incident notes, event information, Configuration Item descriptions, and more in ServiceNow. +- Use [event-based templating][2] to include observation data from event attributes to add meaningful, actionable context to ServiceNow incidents, events, and Configuration Items. +- Keep your ServiceNow username and password secure with Sensu [environment variables and secrets management][9]. + +## Get the plugin + +For a turnkey experience with the Sensu ServiceNow Handler plugin, use one of our curated, configurable quick-start templates: + +- [ServiceNow Incident Management][7]: send Sensu observability alerts to ServiceNow Incident Management. +- [ServiceNow Event Management][3]: send Sensu observability data to ServiceNow Event Management. +- [ServiceNow Configuration Management Database (CMDB)][8]: register Sensu entities as configuration items in ServiceNow CMDB. + +You can also add the [Sensu ServiceNow Handler plugin][4] with a dynamic runtime asset from Bonsai, the Sensu asset hub, to build your own workflow or integrate Sensu with your existing ServiceNow workflows. +[Dynamic runtime assets][5] are shareable, reusable packages that make it easier to deploy Sensu plugins. + + +[1]: ../../../observability-pipeline/observe-process/handlers/ +[2]: ../../../observability-pipeline/observe-process/handler-templates/ +[3]: https://github.com/sensu/catalog/blob/docs-archive/integrations/servicenow/servicenow-events.yaml +[4]: https://bonsai.sensu.io/assets/sensu/sensu-servicenow-handler +[5]: ../../assets/ +[7]: https://github.com/sensu/catalog/blob/docs-archive/integrations/servicenow/servicenow-incident.yaml +[8]: https://github.com/sensu/catalog/blob/docs-archive/integrations/servicenow/servicenow-cmdb.yaml +[9]: ../../../operations/manage-secrets/ diff --git a/content/sensu-go/6.12/plugins/featured-integrations/slack.md b/content/sensu-go/6.12/plugins/featured-integrations/slack.md new file mode 100644 index 0000000000..28b096049c --- /dev/null +++ b/content/sensu-go/6.12/plugins/featured-integrations/slack.md @@ -0,0 +1,45 @@ +--- +title: "Slack integration" +linkTitle: "Slack" +description: "Use the Sensu Slack Handler integration to send alerts to the Slack channels you specify based on Sensu Go observability event data." +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: featured-integrations +--- + +The [Sensu Slack Handler plugin][4] is a Sensu [handler][1] that sends alerts based on your event data. +With this handler, Sensu can trigger alerts to the Slack channels you specify based on event data generated by your Sensu checks. + +{{% notice protip %}} +**PRO TIP**: Use the [Sensu Catalog](../../../catalog/sensu-catalog/) to enable this integration directly from your browser. +Follow the Catalog prompts to configure the Sensu resources you need and start processing your observability data with a few clicks. +{{% /notice %}} + +## Features + +- Use [event-based templating][2] to include observation data from event attributes in your alerts to add meaningful, actionable context. +- Keep your Slack webhook secure with Sensu [environment variables and secrets management][7]. + +## Get the plugin + +For a turnkey experience with the Sensu Slack Handler plugin, use the [Sensu Catalog][10] in the web UI to configure and install it. +Or, use our curated, configurable [quick-start template][8] to integrate Sensu with your existing workflows and send alerts to Slack channels. + +To build your own workflow or integrate Sensu with existing workflows, add the [Sensu Slack Handler plugin][4] with a dynamic runtime asset from Bonsai, the Sensu asset hub. +[Dynamic runtime assets][5] are shareable, reusable packages that make it easier to deploy Sensu plugins. + +## More resources + +Read [Send Slack alerts with handlers][3] to learn how to add and configure the Sensu Slack Handler plugin. + + +[1]: ../../../observability-pipeline/observe-process/handlers/ +[2]: ../../../observability-pipeline/observe-process/handler-templates/ +[3]: ../../../observability-pipeline/observe-process/send-slack-alerts/ +[4]: https://bonsai.sensu.io/assets/sensu/sensu-slack-handler +[5]: ../../assets/ +[7]: ../../../operations/manage-secrets/ +[8]: https://github.com/sensu/catalog/blob/docs-archive/integrations/slack/slack.yaml +[10]: ../../../catalog/sensu-catalog/ diff --git a/content/sensu-go/6.12/plugins/featured-integrations/sumologic.md b/content/sensu-go/6.12/plugins/featured-integrations/sumologic.md new file mode 100644 index 0000000000..c9bd98814c --- /dev/null +++ b/content/sensu-go/6.12/plugins/featured-integrations/sumologic.md @@ -0,0 +1,49 @@ +--- +title: "Sumo Logic integration" +linkTitle: "Sumo Logic" +description: "Use the Sensu Sumo Logic Handler integration to send Sensu observability events and metrics to a Sumo Logic HTTP Logs and Metrics Source." +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: featured-integrations +--- + +The [Sensu Sumo Logic Handler plugin][4] is a Sensu [handler][1] that sends Sensu observability events and metrics to a Sumo Logic [HTTP Logs and Metrics Source][9]. +This handler sends Sensu events as log entries, a set of metrics, or both, depending on the mode of operation you specify. + +{{% notice protip %}} +**PRO TIP**: Use the [Sensu Catalog](../../../catalog/sensu-catalog/) to enable this integration directly from your browser. +Follow the Catalog prompts to configure the Sensu resources you need and start processing your observability data with a few clicks. +{{% /notice %}} + +## Features + +- Query events and metrics points within Sumo Logic: the handler automatically mutates metrics data by creating a top-level object with metric point names and their associated values. +- Tunable arguments: use Sensu annotations to set Sumo Logic source name, host, and category; metric dimensions; log fields; and more. +- Use [event-based templating][2] to include observation data from event attributes to add meaningful, actionable context. +- Keep your Sumo Logic HTTP Logs and Metrics Source URL secure with Sensu [environment variables and secrets management][7]. + +## Get the plugin + +For a turnkey experience with the Sensu Sumo Logic Handler plugin, use the [Sensu Catalog][10] in the web UI to configure and install it. +Or, use our curated, configurable quick-start templates for [event storage][6] and [metric storage][8] to integrate Sensu with your existing workflows and send observation data to an HTTP Logs and Metrics Source. + +To build your own workflow or integrate Sensu with existing workflows, add the [Sensu Sumo Logic Handler plugin][4] with a dynamic runtime asset from Bonsai, the Sensu asset hub. +[Dynamic runtime assets][5] are shareable, reusable packages that make it easier to deploy Sensu plugins. + +## More resources + +Read [Send data to Sumo Logic with Sensu][3] to learn how to add and configure a handler that uses the Sensu Sumo Logic Handler plugin. + + +[1]: ../../../observability-pipeline/observe-process/handlers/ +[2]: ../../../observability-pipeline/observe-process/handler-templates/ +[3]: ../../../observability-pipeline/observe-process/send-data-sumo-logic/ +[4]: https://bonsai.sensu.io/assets/sensu/sensu-sumologic-handler +[5]: ../../assets/ +[6]: https://github.com/sensu/catalog/blob/docs-archive/integrations/sumologic/sumologic-events.yaml +[7]: ../../../operations/manage-secrets/ +[8]: https://github.com/sensu/catalog/blob/docs-archive/integrations/sumologic/sumologic-metrics-handler.yaml +[9]: https://help.sumologic.com/03Send-Data/Sources/02Sources-for-Hosted-Collectors/HTTP-Source +[10]: ../../../catalog/sensu-catalog/ diff --git a/content/sensu-go/6.12/plugins/featured-integrations/timescaledb.md b/content/sensu-go/6.12/plugins/featured-integrations/timescaledb.md new file mode 100644 index 0000000000..56b3528312 --- /dev/null +++ b/content/sensu-go/6.12/plugins/featured-integrations/timescaledb.md @@ -0,0 +1,37 @@ +--- +title: "TimescaleDB integration" +linkTitle: "TimescaleDB" +description: "Use the Sensu TimescaleDB Handler integration to send Sensu metrics to time-series database TimescaleDB so you can store, instrument, and visualize Sensu data." +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: featured-integrations +--- + +The [Sensu TimescaleDB Handler plugin][4] is a Sensu [handler][1] that sends Sensu metrics to the time-series database TimescaleDB so you can store, instrument, and visualize Sensu metrics data. + +{{% notice protip %}} +**PRO TIP**: Use the [Sensu Catalog](../../../catalog/sensu-catalog/) to enable this integration directly from your browser. +Follow the Catalog prompts to configure the Sensu resources you need and start processing your observability data with a few clicks. +{{% /notice %}} + +## Features + +- Transform metrics to TimescaleDB format: extract and transform the metrics you collect from different sources in formats like Graphite, OpenTSDB, Nagios, and Influx and populate them into TimescaleDB. +- Specify custom values for Sensu event metric points via [metric tags][3]. + +## Get the plugin + +For a turnkey experience with the Sensu TimescaleDB Handler plugin, use the [Sensu Catalog][10] in the web UI to configure and install it. + +To build your own workflow or integrate Sensu with existing workflows, you can also add the [Sensu TimescaleDB Handler plugin][4] with a dynamic runtime asset from Bonsai, the Sensu asset hub. +[Dynamic runtime assets][5] are shareable, reusable packages that make it easier to deploy Sensu plugins. + + +[1]: ../../../observability-pipeline/observe-process/handlers/ +[2]: ../../../observability-pipeline/observe-process/handler-templates/ +[3]: ../../../observability-pipeline/observe-schedule/checks/#output-metric-tags +[4]: https://github.com/sensu/catalog/blob/docs-archive/integrations/timescaledb/timescaledb.yaml +[5]: ../../assets/ +[10]: ../../../catalog/sensu-catalog/ diff --git a/content/sensu-go/6.12/plugins/featured-integrations/wavefront.md b/content/sensu-go/6.12/plugins/featured-integrations/wavefront.md new file mode 100644 index 0000000000..dc783ec28e --- /dev/null +++ b/content/sensu-go/6.12/plugins/featured-integrations/wavefront.md @@ -0,0 +1,41 @@ +--- +title: "Wavefront integration" +linkTitle: "Wavefront" +description: "Use the Sensu Wavefront Handler integration to send Sensu metrics to Wavefront so you can store, instrument, and visualize Sensu data in an Wavefront database." +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: featured-integrations +--- + +The [Sensu Wavefront Handler plugin][4] is a Sensu [handler][1] that sends Sensu metrics to Wavefront via a proxy, which allows you to store, instrument, and visualize Sensu metrics data in an Wavefront database. + +{{% notice protip %}} +**PRO TIP**: Use the [Sensu Catalog](../../../catalog/sensu-catalog/) to enable this integration directly from your browser. +Follow the Catalog prompts to configure the Sensu resources you need and start processing your observability data with a few clicks. +{{% /notice %}} + +## Features + +- Transform metrics to Wavefront format: extract and transform the metrics you collect from different sources in formats like Graphite, OpenTSDB, Nagios, and Influx and populate them into Wavefront. +- Specify additional tags to include when processing metrics with the Wavefront plugin's `tags` flag or [metric tags][7]. +- Keep your Graphite host and port secure with Sensu [environment variables and secrets management][6]. + +## Get the plugin + +For a turnkey experience with the Sensu Wavefront Handler plugin, use the [Sensu Catalog][10] in the web UI to configure and install it. +Or, use our curated, configurable [quick-start template][3] to integrate Sensu with your existing workflows and store Sensu metrics in Wavefront. + +To build your own workflow or integrate Sensu with existing workflows, add the [Sensu Wavefront Handler plugin][4] with a dynamic runtime asset from Bonsai, the Sensu asset hub. +[Dynamic runtime assets][5] are shareable, reusable packages that make it easier to deploy Sensu plugins. + + +[1]: ../../../observability-pipeline/observe-process/handlers/ +[2]: ../../../observability-pipeline/observe-process/handler-templates/ +[3]: https://github.com/sensu/catalog/blob/docs-archive/integrations/wavefront/wavefront.yaml +[4]: https://bonsai.sensu.io/assets/sensu/sensu-wavefront-handler +[5]: ../../assets/ +[6]: ../../../operations/manage-secrets/ +[7]: ../../../observability-pipeline/observe-schedule/checks/#output-metric-tags +[10]: ../../../catalog/sensu-catalog/ diff --git a/content/sensu-go/6.12/plugins/install-plugins.md b/content/sensu-go/6.12/plugins/install-plugins.md new file mode 100644 index 0000000000..9e7b1c9e65 --- /dev/null +++ b/content/sensu-go/6.12/plugins/install-plugins.md @@ -0,0 +1,142 @@ +--- +title: "Install Sensu plugins" +linkTitle: "Install Plugins" +description: "Learn how to install plugins to extend Sensu's functionality with executables for performing checks, mutators, and handlers." +weight: 60 +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: plugins +--- + +Extend Sensu's functionality with plugins, which provide executables for performing status or metric checks, mutators for changing data to a desired format, and handlers for performing an action on a Sensu event. + +## Install plugins with dynamic runtime assets + +Dynamic runtime assets are shareable, reusable packages that make it easier to deploy Sensu plugins. +Read [Use dynamic runtime assets to install plugins][7] to become familiar with workflows that involve assets. + +{{% notice note %}} +**NOTE**: Dynamic runtime assets are not required to use Sensu Go. +You can install Sensu plugins using the [sensu-install](#install-plugins-with-the-sensu-install-tool) tool or a [configuration management](../../operations/deploy-sensu/configuration-management/) solution. +{{% /notice %}} + +Use the [Sensu Catalog][10] to find, configure, and install many plugins directly from your browser. +Follow the Catalog prompts to configure the Sensu resources you need and start processing your observability data with a few clicks. + +You can also use [Bonsai, the Sensu asset hub][8], a centralized place for downloading and sharing dynamic runtime assets. +Bonsai lists hundreds of plugins, libraries, and runtimes with instructions and examples to help you automate your monitoring workflows. +You can also [share your asset on Bonsai][9]. + +## Install plugins with the sensu-install tool + +To use community plugins that are not yet compatible with Sensu Go, use the `sensu-install` tool. + +If you've used previous versions of Sensu, you're probably familiar with the [Sensu Community Plugins][1] organization on GitHub. +Although some of these plugins are enabled for Sensu Go, some do not include the components necessary to work with Sensu Go. +Read each plugin's instructions for information about whether it is compatibile with Sensu Go. + +{{% notice note %}} +**NOTE**: Plugins in the Sensu Plugins GitHub organization are community-maintained: anyone can improve on them. +To get started with adding to a plugin or sharing your own, head to the [Sensu Community Slack channel](https://slack.sensu.io/). +Maintainers are always happy to help answer questions and point you in the right direction. +{{% /notice %}} + +The `sensu-install` tool comes with an embedded version of Ruby, so you don't need to have Ruby installed on your system. + +To install a [Sensu Community plugin][1] with Sensu Go: + +1. Install the [sensu-plugins-ruby package][2] from packagecloud. + +2. Run the `sensu-install` command to install plugins in the [Sensu Community Plugins GitHub organization][1] by repository name. +Plugins are installed into `/opt/sensu-plugins-ruby/embedded/bin`. + +To list all flags for the sensu-install command, run: + +{{< code shell >}} +sensu-install --help +{{< /code >}} + +The response will be similar to this example: + +{{< code text >}} +Usage: sensu-install [options] + -h, --help Display this message + -v, --verbose Enable verbose logging + -p, --plugin PLUGIN Install a Sensu PLUGIN + -P, --plugins PLUGIN[,PLUGIN] PLUGIN or comma-delimited list of Sensu plugins to install + -e, --extension EXTENSION Install a Sensu EXTENSION + -E, --extensions EXTENSION[,EXT] EXTENSION or comma-delimited list of Sensu extensions to install + -s, --source SOURCE Install Sensu plugins and extensions from a custom SOURCE + -c, --clean Clean up (remove) other installed versions of the plugin(s) and/or extension(s) + -x, --proxy PROXY Install Sensu plugins and extensions via a PROXY URL +{{< /code >}} + +For example, to install the [Sensu InfluxDB plugin][6]: + +{{< code shell >}} +sudo sensu-install -p influxdb +{{< /code >}} + +To install a specific version of the Sensu InfluxDB plugin with `sensu-install`, run: + +{{< code shell >}} +sudo sensu-install -p 'sensu-plugins-influxdb:2.0.0' +{{< /code >}} + +{{% notice note %}} +**NOTE**: We recommend specifying the plugin version you want to install to maintain the stability of your observability infrastructure. +If you do not specify a version to install, Sensu automatically installs the latest version, which may include breaking changes. +{{% /notice %}} + +Use a configuration management tool or [Sensu dynamic runtime assets][5] to pin the versions of any plugins installed in production. + +{{% notice note %}} +**NOTE**: If a plugin is not Sensu Go-enabled and there is no analogue on Bonsai, you can add the necessary functionality to make the plugin compatible with Sensu Go. +Follow the Discourse guide [Contributing Assets for Existing Ruby Sensu Plugins](https://discourse.sensu.io/t/contributing-assets-for-existing-ruby-sensu-plugins/1165) to walk through the process. +{{% /notice %}} + +### Troubleshoot the sensu-install tool + +Some plugins require additional tools to install them successfully. +An example is the [Sensu disk checks plugin][3]. + +To download and update package information: + +{{< language-toggle >}} + +{{< code shell "Debian family" >}} +sudo apt-get update +{{< /code >}} + +{{< code shell "RHEL family" >}} +sudo yum update +{{< /code >}} + +{{< /language-toggle >}} + +Depending on the plugin, you may need to install developer tool packages: + +{{< language-toggle >}} + +{{< code shell "Debian family" >}} +sudo apt-get install build-essential +{{< /code >}} + +{{< code shell "RHEL family" >}} +sudo yum groupinstall "Development Tools" +{{< /code >}} + +{{< /language-toggle >}} + + +[1]: https://github.com/sensu-plugins/ +[2]: https://packagecloud.io/sensu/community/ +[3]: https://github.com/sensu-plugins/sensu-plugins-disk-checks/ +[5]: ../assets/ +[6]: https://github.com/sensu-plugins/sensu-plugins-influxdb/ +[7]: ../use-assets-to-install-plugins/ +[8]: https://bonsai.sensu.io/ +[9]: ../assets#share-an-asset-on-bonsai +[10]: ../../catalog/sensu-catalog/ diff --git a/content/sensu-go/6.12/plugins/plugins.md b/content/sensu-go/6.12/plugins/plugins.md new file mode 100644 index 0000000000..85b4207112 --- /dev/null +++ b/content/sensu-go/6.12/plugins/plugins.md @@ -0,0 +1,162 @@ +--- +title: "Plugins reference" +linkTitle: "Plugins Reference" +reference_title: "Plugins" +type: "reference" +description: "Read this reference for information about Sensu plugins, which provide executables that you can use as a Sensu check, handler, or mutator command." +weight: 40 +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: plugins +--- + +Sensu plugins provide executable scripts or other programs that you can use as Sensu checks, handlers, and mutators. +Sensu plugins must comply with the following specification: + +- Accept input/data via stdin (handler and mutator plugins only) + - Optionally able to parse a JSON data payload (that is, observation data in an event) +- Output data to stdout or stderr +- Produce an exit status code to indicate state: + - `0` indicates `OK` + - `1` indicates `WARNING` + - `2` indicates `CRITICAL` + - exit status codes other than `0`, `1`, or `2` indicate an unknown or custom + status +- Optionally able to parse command line arguments to modify plugin behavior + +## Supported programming languages + +You can use any programming language that can satisfy the Sensu plugin specification requirements — which is nearly any programming language in the world — to write Sensu plugins. + +Using plugins written in programming languages other than Go requires you to install the corresponding runtime. +For example, to use a Ruby plugin with Sensu Go, you must install the [Sensu Go Ruby Runtime asset][3]. + +### Use Nagios plugins + +The Sensu plugin specification is compatible with the [Nagios plugin specification][9], so you can use the 50+ plugins in the official [Nagios Plugins project][10] and 4000+ plugins in the [Nagios Exchange][11] with Sensu without any modification. + +## Plugin execution + +All plugins are executed by the Sensu backend. +Plugins must be executable files that are discoverable on the Sensu system (that is, installed in a system `$PATH` directory) or referenced with an absolute path (for example, `/opt/path/to/my/plugin`). + +{{% notice note %}} +**NOTE**: By default, Sensu installer packages will modify the system `$PATH` for the Sensu processes to include `/etc/sensu/plugins`. +As a result, executable scripts (for example, plugins) located in `/etc/sensu/plugins` will be valid commands. +This allows command attributes to use relative paths for Sensu plugin commands, such as `"command": "http-check --url https://sensu.io"`. +{{% /notice %}} + +## Plugin configuration overrides + +Many plugins support configuration overrides on a per-entity or per-check basis. +For example, some plugins allow you to use annotations in individual entities and checks to set arguments that will override any arguments set in a resource command or in backend runtime environment variables for only that entity or check. + +Read the [Bonsai][12] documentation for a plugin to learn about any configuration overrides the plugin supports. + +## Go plugin example + +The following example shows the structure for a very basic Sensu Go plugin. + +{{< code go >}} +package main + +import ( + "fmt" + "log" + + "github.com/sensu-community/sensu-plugin-sdk/sensu" + "github.com/sensu/sensu-go/types" +) + +// Config represents the check plugin config. +type Config struct { + sensu.PluginConfig + Example string +} + +var ( + plugin = Config{ + PluginConfig: sensu.PluginConfig{ + Name: "check_name", + Short: "Description for check_name", + Keyspace: "sensu.io/plugins/check_name/config", + }, + } + + options = []*sensu.PluginConfigOption{ + &sensu.PluginConfigOption{ + Path: "example", + Env: "CHECK_EXAMPLE", + Argument: "example", + Shorthand: "e", + Default: "", + Usage: "An example string configuration option", + Value: &plugin.Example, + }, + } +) + +func main() { + check := sensu.NewGoCheck(&plugin.PluginConfig, options, checkArgs, executeCheck, false) + check.Execute() +} + +func checkArgs(event *types.Event) (int, error) { + if len(plugin.Example) == 0 { + return sensu.CheckStateWarning, fmt.Errorf("--example or CHECK_EXAMPLE environment variable is required") + } + return sensu.CheckStateOK, nil +} + +func executeCheck(event *types.Event) (int, error) { + log.Println("executing check with --example", plugin.Example) + return sensu.CheckStateOK, nil +} +{{< /code >}} + + +To create this scaffolding for a Sensu Go check, handler, mutator, or sensuctl plugin, use the [Sensu Plugin Tool][4] along with a [default plugin template][5]. +The plugin template repositories wrap the [Sensu Plugin SDK][8], which provides the framework for building Sensu Go plugins. + +For a step-by-step walkthrough, read [How to publish an asset with the Sensu Go SDK][7] — you'll learn how to create a check plugin and a handler plugin with the Sensu Plugin SDK. +You can also watch our 30-minute webinar, [Intro to assets with the Sensu Go SDK][6], and learn to build a check plugin for Sensu Go. + +## Ruby plugin example + +The following example demonstrates a very basic Sensu plugin in the Ruby programming language. + +{{< code ruby >}} +#!/usr/bin/env ruby +# +require 'json' + +# Read the incoming JSON data from stdin +event = JSON.parse(stdin.read, :symbolize_names => true) + +# Create an output object using Ruby string interpolation +output = "The check named #{event[:check][:name]} generated the following output: #{event[:output]}" + +# Convert the mutated event data back to JSON and output it to stdout +puts output +{{< /code >}} + +{{% notice note %}} +**NOTE**: This example is intended as a starting point for building a basic custom plugin in Ruby. +It does not provide functionality. +{{% /notice %}} + + +[1]: #supported-programming-languages +[2]: https://github.com/sensu-plugins/sensu-plugins-http +[3]: https://bonsai.sensu.io/assets/sensu/sensu-ruby-runtime +[4]: https://github.com/sensu-community/sensu-plugin-tool +[5]: https://github.com/sensu-community/sensu-plugin-tool#overview +[6]: https://sensu.io/resources/webinar/intro-to-assets-with-the-sensu-go-sdk +[7]: https://sensu.io/blog/how-to-publish-an-asset-with-the-sensu-go-sdk +[8]: https://github.com/sensu-community/sensu-plugin-sdk +[9]: https://assets.nagios.com/downloads/nagioscore/docs/nagioscore/3/en/pluginapi.html +[10]: https://www.nagios.org/downloads/nagios-plugins/ +[11]: https://exchange.nagios.org/ +[12]: https://bonsai.sensu.io/ diff --git a/content/sensu-go/6.12/plugins/use-assets-to-install-plugins.md b/content/sensu-go/6.12/plugins/use-assets-to-install-plugins.md new file mode 100644 index 0000000000..6a24b95e1a --- /dev/null +++ b/content/sensu-go/6.12/plugins/use-assets-to-install-plugins.md @@ -0,0 +1,249 @@ +--- +title: "Use dynamic runtime assets to install plugins" +linkTitle: "Use Assets to Install Plugins" +guide_title: "Use dynamic runtime assets to install plugins" +type: "guide" +description: "Use Sensu's shareable, reusable dynamic runtime assets to deploy the plugins, libraries, and runtimes you need for your monitoring and observability workflows." +weight: 80 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: plugins +--- + +Dynamic runtime assets are shareable, reusable packages that make it easier to deploy Sensu plugins. +You can use assets to provide the plugins, libraries, and runtimes you need to automate your monitoring workflows. +Read the [asset reference][1] for more information about dynamic runtime assets. +This guide uses the [sensu/sensu-pagerduty-handler][7] dynamic runtime asset as an example. + +{{% notice note %}} +**NOTE**: Dynamic runtime assets are not required to use Sensu Go. +You can install Sensu plugins using the [sensu-install](../install-plugins#install-plugins-with-the-sensu-install-tool) tool or a [configuration management](../../operations/deploy-sensu/configuration-management/) solution. +{{% /notice %}} + +## Register an asset + +To add the [sensu/sensu-pagerduty-handler][7] dynamic runtime asset to Sensu, use [sensuctl asset add][6]: + +{{< code shell >}} +sensuctl asset add sensu/sensu-pagerduty-handler:2.2.0 -r pagerduty-handler +{{< /code >}} + +The response should be similar to this example: + +{{< code text >}} +fetching bonsai asset: sensu/sensu-pagerduty-handler:2.2.0 +added asset: sensu/sensu-pagerduty-handler:2.2.0 + +You have successfully added the Sensu asset resource, but the asset will not get downloaded until +it's invoked by another Sensu resource (ex. check). To add this runtime asset to the appropriate +resource, populate the "runtime_assets" field with ["pagerduty-handler"]. +{{< /code >}} + +{{% notice note %}} +**NOTE**: Specify the asset version you want to install to maintain the stability of your observability infrastructure. +If you do not specify a version to install, Sensu automatically installs the latest version, which may include breaking changes. +{{% /notice %}} + +This example uses the `-r` (rename) flag to specify a shorter name for the asset: `pagerduty-handler`. + +You can also open the **Release Assets** tab on asset pages in [Bonsai][3] to download the asset definition for your Sensu backend platform and architecture. + +{{% notice note %}} +**NOTE**: Sensu does not download and install asset builds onto the system until they are needed for command execution. +Read the [asset reference](../assets#dynamic-runtime-asset-builds) for more information about asset builds. +{{% /notice %}} + +If you are using a Sensu [package][9], the asset is installed at `/var/cache`. +If you are using a Sensu [Docker image][17], the asset is installed at `/var/lib`. + +## Adjust the asset definition + +Asset definitions tell Sensu how to download and verify the asset when required by a check, filter, mutator, or handler. + +After you add or download the asset definition, open the file and adjust the `namespace` and `filters` for your Sensu instance. +Here's the asset definition for version 2.2.0 of the [sensu/sensu-pagerduty-handler][7] asset for Linux AMD64: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Asset +api_version: core/v2 +metadata: + annotations: + io.sensu.bonsai.api_url: https://bonsai.sensu.io/api/v1/assets/sensu/sensu-pagerduty-handler + io.sensu.bonsai.name: sensu-pagerduty-handler + io.sensu.bonsai.namespace: sensu + io.sensu.bonsai.tags: handler + io.sensu.bonsai.tier: Supported + io.sensu.bonsai.url: https://bonsai.sensu.io/assets/sensu/sensu-pagerduty-handler + io.sensu.bonsai.version: 2.2.0 + name: pagerduty-handler +spec: + builds: + - filters: + - entity.system.os == 'linux' + - entity.system.arch == 'amd64' + headers: null + sha512: adc6ee846b88a792cc0f384a942f8b7ff727c7d7cf6a3012a0bf97ae4bef770503f9d5c26f756047559c145ac01c62d4db9af8574d0cc451a176f1be29f52ffc + url: https://assets.bonsai.sensu.io/87f00332d6f36f59ee188e9e2a94a2b84172d134/sensu-pagerduty-handler_2.2.0_linux_amd64.tar.gz +{{< /code >}} + +{{< code json >}} +{ + "type": "Asset", + "api_version": "core/v2", + "metadata": { + "annotations": { + "io.sensu.bonsai.api_url": "https://bonsai.sensu.io/api/v1/assets/sensu/sensu-pagerduty-handler", + "io.sensu.bonsai.name": "sensu-pagerduty-handler", + "io.sensu.bonsai.namespace": "sensu", + "io.sensu.bonsai.tags": "handler", + "io.sensu.bonsai.tier": "Supported", + "io.sensu.bonsai.url": "https://bonsai.sensu.io/assets/sensu/sensu-pagerduty-handler", + "io.sensu.bonsai.version": "2.2.0" + }, + "name": "pagerduty-handler" + }, + "spec": { + "builds": [ + { + "filters": [ + "entity.system.os == 'linux'", + "entity.system.arch == 'amd64'" + ], + "headers": null, + "sha512": "adc6ee846b88a792cc0f384a942f8b7ff727c7d7cf6a3012a0bf97ae4bef770503f9d5c26f756047559c145ac01c62d4db9af8574d0cc451a176f1be29f52ffc", + "url": "https://assets.bonsai.sensu.io/87f00332d6f36f59ee188e9e2a94a2b84172d134/sensu-pagerduty-handler_2.2.0_linux_amd64.tar.gz" + } + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +Filters for _check_ dynamic runtime assets should match entity platforms. +Filters for _handler and filter_ dynamic runtime assets should match your Sensu backend platform. +If the provided filters are too restrictive for your platform, replace `os` and `arch` with any supported [entity system attributes][4] (for example, `entity.system.platform_family == 'rhel'`). +You may also want to customize the asset `name` to reflect the supported platform (for example, `pagerduty-handler-linux`) and add custom attributes with [`labels` and `annotations`][5]. + +**Enterprise-tier dynamic runtime assets** (like the [ServiceNow][10] and [Jira][11] event handlers) require a Sensu commercial license. +For more information about commercial features and to activate your license, read [Get started with commercial features][12]. + +Use sensuctl to verify that the asset is registered and ready to use: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl asset list --format yaml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl asset list --format wrapped-json +{{< /code >}} + +{{< /language-toggle >}} + +## Create a workflow + +With the asset downloaded and registered, you can use it in a monitoring workflow. +Dynamic runtime assets may provide executable plugins intended for use with a Sensu check, handler, mutator, or hook, or JavaScript libraries intended to provide functionality for use in event filters. +The details in Bonsai are the best resource for information about each asset's capabilities and configuration. + +For example, to use the [Sensu PagerDuty Handler][7] asset, you would create a `pagerduty` handler that includes your PagerDuty service API key in place of `SECRET` and `pagerduty-handler` as a runtime asset: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Handler +api_version: core/v2 +metadata: + name: pagerduty +spec: + command: sensu-pagerduty-handler + env_vars: + - PAGERDUTY_TOKEN=SECRET + filters: + - is_incident + runtime_assets: + - pagerduty-handler + timeout: 10 + type: pipe +{{< /code >}} + +{{< code json >}} +{ + "type": "Handler", + "api_version": "core/v2", + "metadata": { + "name": "pagerduty" + }, + "spec": { + "type": "pipe", + "command": "sensu-pagerduty-handler", + "env_vars": [ + "PAGERDUTY_TOKEN=SECRET" + ], + "runtime_assets": [ + "pagerduty-handler" + ], + "timeout": 10, + "filters": [ + "is_incident" + ] + } +} +{{< /code >}} + +{{< /language-toggle >}} + +Save the definition to a file (for example, `pagerduty-handler.yml` or `pagerduty-handler.json`), and add it to Sensu with sensuctl: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl create --file pagerduty-handler.yml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl create --file pagerduty-handler.json +{{< /code >}} + +{{< /language-toggle >}} + +Now that Sensu can create incidents in PagerDuty, you can automate this workflow by adding the `pagerduty` handler to your Sensu service check definitions. +Read [Monitor server resources][13] to learn more. + +## Next steps + +Read these resources for more information about using dynamic runtime assets in Sensu: + +- [Assets reference][1] +- [Asset format specification][14] +- [Share assets on Bonsai][15] + +Follow [Send PagerDuty alerts with Sensu][8] to configure a check that generates status events and a handler that sends Sensu alerts to PagerDuty for non-OK events. + + +[1]: ../assets/ +[2]: #create-an-asset +[3]: https://bonsai.sensu.io +[4]: ../../observability-pipeline/observe-entities/entities/#system-attributes +[5]: ../assets#metadata-attributes +[6]: ../../sensuctl/sensuctl-bonsai/#install-dynamic-runtime-asset-definitions +[7]: https://bonsai.sensu.io/assets/sensu/sensu-pagerduty-handler +[8]: ../../observability-pipeline/observe-process/send-pagerduty-alerts/ +[9]: ../../platforms/#supported-packages +[10]: https://bonsai.sensu.io/assets/sensu/sensu-servicenow-handler +[11]: https://bonsai.sensu.io/assets/sensu/sensu-jira-handler +[12]: ../../commercial/ +[13]: ../../observability-pipeline/observe-schedule/monitor-server-resources/ +[14]: ../assets#dynamic-runtime-asset-format-specification +[15]: ../assets#share-an-asset-on-bonsai +[16]: https://bonsai.sensu.io +[17]: ../../platforms/#docker-images diff --git a/content/sensu-go/6.12/reference/_index.md b/content/sensu-go/6.12/reference/_index.md new file mode 100644 index 0000000000..e5c4811069 --- /dev/null +++ b/content/sensu-go/6.12/reference/_index.md @@ -0,0 +1,18 @@ +--- +title: "Reference Index" +linkTitle: "Reference Index" +description: "Read the reference documentation for information about Sensu resources, specifications, and example configurations." +product: "Sensu Go" +version: "6.12" +weight: 100 +layout: "single" +toc: false +menu: + sensu-go-6.12: + identifier: reference +--- + +This index links to every reference in the Sensu documentation. +Reference documentation includes specifications, examples, configuration notes, and other details about Sensu resources, the agent and backend, and Sensu query expressions. + +{{< reftypeListing >}} diff --git a/content/sensu-go/6.12/release-notes.md b/content/sensu-go/6.12/release-notes.md new file mode 100644 index 0000000000..9de2a76d23 --- /dev/null +++ b/content/sensu-go/6.12/release-notes.md @@ -0,0 +1,2693 @@ +--- +title: "Sensu Go release notes" +linkTitle: "Release Notes" +description: "Read the Sensu Go release notes to learn what's new in our latest release and get information about upgrading to the latest version of Sensu Go." +weight: -80 +product: "Sensu Go" +toc: false +version: "6.12" +menu: "sensu-go-6.12" +--- + +- [6.12.0 release notes](#6120-release-notes) +- [6.11.0 release notes](#6110-release-notes) +- [6.10.0 release notes](#6100-release-notes) +- [6.9.2 release notes](#692-release-notes) +- [6.9.1 release notes](#691-release-notes) +- [6.9.0 release notes](#690-release-notes) +- [6.8.2 release notes](#682-release-notes) +- [6.8.1 release notes](#681-release-notes) +- [6.8.0 release notes](#680-release-notes) +- [6.7.5 release notes](#675-release-notes) +- [6.7.4 release notes](#674-release-notes) +- [6.7.3 release notes](#673-release-notes) +- [6.7.2 release notes](#672-release-notes) +- [6.7.1 release notes](#671-release-notes) +- [6.7.0 release notes](#670-release-notes) +- [6.6.6 release notes](#666-release-notes) +- [6.6.5 release notes](#665-release-notes) +- [6.6.4 release notes](#664-release-notes) +- [6.6.3 release notes](#663-release-notes) +- [6.6.2 release notes](#662-release-notes) +- [6.6.1 release notes](#661-release-notes) +- [6.6.0 release notes](#660-release-notes) +- [6.5.5 release notes](#655-release-notes) +- [6.5.4 release notes](#654-release-notes) +- [6.5.3 release notes](#653-release-notes) +- [6.5.2 release notes](#652-release-notes) +- [6.5.1 release notes](#651-release-notes) +- [6.5.0 release notes](#650-release-notes) +- [6.4.3 release notes](#643-release-notes) +- [6.4.2 release notes](#642-release-notes) +- [6.4.1 release notes](#641-release-notes) +- [6.4.0 release notes](#640-release-notes) +- [6.3.0 release notes](#630-release-notes) +- [6.2.7 release notes](#627-release-notes) +- [6.2.6 release notes](#626-release-notes) +- [6.2.5 release notes](#625-release-notes) +- [6.2.4 release notes](#624-release-notes) +- [6.2.3 release notes](#623-release-notes) +- [6.2.2 release notes](#622-release-notes) +- [6.2.1 release notes](#621-release-notes) +- [6.2.0 release notes](#620-release-notes) +- [6.1.4 release notes](#614-release-notes) +- [6.1.3 release notes](#613-release-notes) +- [6.1.2 release notes](#612-release-notes) +- [6.1.1 release notes](#611-release-notes) +- [6.1.0 release notes](#610-release-notes) +- [6.0.0 release notes](#600-release-notes) +- [5.21.5 release notes](#5215-release-notes) +- [5.21.4 release notes](#5214-release-notes) +- [5.21.3 release notes](#5213-release-notes) +- [5.21.2 release notes](#5212-release-notes) +- [5.21.1 release notes](#5211-release-notes) +- [5.21.0 release notes](#5210-release-notes) +- [5.20.2 release notes](#5202-release-notes) +- [5.20.1 release notes](#5201-release-notes) +- [5.20.0 release notes](#5200-release-notes) +- [5.19.3 release notes](#5193-release-notes) +- [5.19.2 release notes](#5192-release-notes) +- [5.19.1 release notes](#5191-release-notes) +- [5.19.0 release notes](#5190-release-notes) +- [5.18.1 release notes](#5181-release-notes) +- [5.18.0 release notes](#5180-release-notes) +- [5.17.2 release notes](#5172-release-notes) +- [5.17.1 release notes](#5171-release-notes) +- [5.17.0 release notes](#5170-release-notes) +- [5.16.1 release notes](#5161-release-notes) +- [5.16.0 release notes](#5160-release-notes) +- [5.15.0 release notes](#5150-release-notes) +- [5.14.2 release notes](#5142-release-notes) +- [5.14.1 release notes](#5141-release-notes) +- [5.14.0 release notes](#5140-release-notes) +- [5.13.2 release notes](#5132-release-notes) +- [5.13.1 release notes](#5131-release-notes) +- [5.13.0 release notes](#5130-release-notes) +- [5.12.0 release notes](#5120-release-notes) +- [5.11.1 release notes](#5111-release-notes) +- [5.11.0 release notes](#5110-release-notes) +- [5.10.2 release notes](#5102-release-notes) +- [5.10.1 release notes](#5101-release-notes) +- [5.10.0 release notes](#5100-release-notes) +- [5.9.0 release notes](#590-release-notes) +- [5.8.0 release notes](#580-release-notes) +- [5.7.0 release notes](#570-release-notes) +- [5.6.0 release notes](#560-release-notes) +- [5.5.1 release notes](#551-release-notes) +- [5.5.0 release notes](#550-release-notes) +- [5.4.0 release notes](#540-release-notes) +- [5.3.0 release notes](#530-release-notes) +- [5.2.1 release notes](#521-release-notes) +- [5.2.0 release notes](#520-release-notes) +- [5.1.1 release notes](#511-release-notes) +- [5.1.0 release notes](#510-release-notes) +- [5.0.1 release notes](#501-release-notes) +- [5.0.0 release notes](#500-release-notes) + +### Versioning + +Sensu Go adheres to [semantic versioning][2] using MAJOR.MINOR.PATCH release numbers, starting at 5.0.0. +MAJOR version changes indicate incompatible API changes. +MINOR versions add backward-compatible functionality. +PATCH versions include backward-compatible bug fixes. + +### Upgrading + +Read the [upgrade guide][1] for information about upgrading to the latest version of Sensu Go. + +--- + +## 6.12.0 release notes + +**November 13, 2024** — The latest release of Sensu Go, version 6.12.0, is now available for download. + +Read the [upgrade guide][1] to upgrade Sensu to version 6.12.0. + +**NEW FEATURES:** + +- ([Commercial feature][311]) Users can now change their passwords in the web UI. +- Added several backend configuration options: + - Use [enable-cert-revocation-check][314] to enable and disable certificate revocation list (CRL) and Online Certificate Status Protocol (OCSP) checks for SSL certificate revocation. + - Use [default-silenced-expiry-time][313] to specify a default expiration time to apply to silences that do not include the `expire_at` attribute. This configuration option allows you to ensure that all silences have an expiration time. + - Use [max-silenced-expiry-time-allowed][312] to specify the maximum length of time for which silences can be set. + +**IMPROVEMENTS** + +- ([Commercial feature][311]) Upgraded Alpine version from 3.16 to 3.20. +- Added support for Ubuntu 24.04 LTS and Debian 13. +- Upgraded Go version from 1.21.3 to 1.21.11. +- Upgraded etcd version from 3.5.10 to 3.5.15. + +**FIXES** +- ([Commercial feature][311]) In the web UI, opening multiple tabs no longer results in a session timeout failure. +- ([Commercial feature][311]) Fixed an issue that prevented OIDC groups claims from working properly when using Microsft Entra ID. +- Fixed a session cleanup issue that could increase the size of the etcd store. +- Scheduled checks that are manually executed using sensuctl or the web UI now execute successfully and no longer result in a `no matching entity found` error. + +## 6.11.0 release notes + +**January 31, 2024** — The latest release of Sensu Go, version 6.11.0, is now available for download. In this release, we updated our Federal Information Processing Standard (FIPS) builds to use Go's BoringCrypto feature and to remove the binary's dynamic link with OpenSSL. Sensu Go 6.11.0 also includes version bumps for Go, jwt, and Logrus. + +Read the [upgrade guide][1] to upgrade Sensu to version 6.11.0. + +**IMPROVEMENTS** + +- ([Commercial feature][308]) [FIPS builds][310] now use the [BoringCrypto][309] feature in Go instead of the RedHat fork of Go. Binaries are no longer dynamically linked with OpenSSL, and the `require-openssl` configuration option has been removed from the agent and backend. +- Upgraded Go version from `1.17.12` to `1.21.3`. +- Upgraded jwt version from `4.0.0` to `4.4.3`. +- Upgraded Logrus version from `1.6.0` to `1.9.3`. + +## 6.10.0 release notes + +**May 2023** — The latest release of Sensu Go, version 6.10.0, is now available for download. Sensu Go 6.10.0 adds a number of features to let the user specify millisecond timestamps in log files, sort silences by expiration time and let them truncate the system network properties from events, which can greatly reduce the event size. It also addresses vulnerability issues related to sessions and refresh tokens, GraphQL and Hashicorp Vault. Finally it also addresses Web UI inconveniences with among other things pagination, entity list view and the dark color scheme. + +{{% notice note %}} +**NOTE**: Custom commands making use of $SENSU_ACCESS_TOKEN and $SENSU_REFRESH_TOKEN may be impacted by the changes to sessions and refresh tokens. We recommend setting up an API key and using $SENSU_API_KEY in light of these changes. +{{% /notice %}} + +**IMPROVEMENTS** + +- ([Commercial feature][307]) In the web UI, a label was added to the Catalog page to make viewing integrations at a glance easier +- ([Commercial feature][307]) For the web UI configuration, added disable BSM (`disable_bsm: true`) flag to hide BSM from Web UI +- ([Commercial feature][307]) In the web UI, added the ability to sort silences by expiration time +- Added the flag `strip-networks` to the Sensu agent to avoid collecting `system.networks` information +- Added the `log-millisecond-timestamps` backend configuration flag to allow for greater logging precision +- Added a session store to the backend to detect and prevent refresh token reuse + +**FIXES** +- ([Commercial feature][307]) In the web UI, solved a crash when an invalid sort order was specified in the web config +- ([Commercial feature][307]) In the web UI, page pagination sizes are added back +- ([Commercial feature][307]) Fix search parameters persisting when paginating on list views +- ([Commercial feature][307]) In the web UI, handler sets now show configured handlers on handler list page +- ([Commercial feature][307]) In the web UI, fix incorrect URLs displaying in resource labels +- ([Commercial feature][307]) In the web UI, fixed bug on Entity List view where too many subscriptions would cause overflow +- ([Commercial feature][307]) In the web UI, fixed poor color contrast in check result output +- ([Commercial feature][307]) Users are now automatically logged out of the UI after a period of inactivity (12h) +- Handler errors are now logged at "error" level instead of "info." +- Addressed uncontrolled recursion vulnerability ([CVE-2022-37315][306]) by upgrading the graphql-go library to v0.8.1 +- Addressed a number of vulnerabilities in the Hashicorp Vault library by upgrading the vault library to v1.2.1-0.20220920125708-57ac8f323643 + +## 6.9.2 release notes + +**March 8, 2023** — The latest release of Sensu Go, version 6.9.2, is now available for download. + +Sensu Go 6.9.2 fixes a UI crash on the Service Component detail page. Additionally, we added a GraphQL validator for query node depth to prevent a potential unauthenticated user DDoS. + +**FIXES:** + +- ([Commercial feature][303]) In the web UI, added GraphQL validator for query node depth to prevent a potential unauthenticated user DDoS. +- ([Commercial feature][303]) In the web UI, fixed an issue causing crashes when viewing BSM Service Component detail pages. + +## 6.9.1 release notes + +**December 1, 2022** — The latest release of Sensu Go, version 6.9.1, is now available for download. + +Sensu Go 6.9.1 fixes a UI XSS vulnerability issue that could be caused by a malicious check output and addresses a crash in the pipeline edit page. Additionally we addressed issues with the entity details page's event list, reimplemented the saved searches on the entity list view and fixed a few erroneous URLs. + +**FIXES:** + +- Fixed Graphql Selectors bug that caused the entity page to show events for all entities. +- ([Commercial feature][303]) In the web UI, added labels to Catalog list view items for easier readability. +- ([Commercial feature][303]) In the web UI, fixed the Github URL for feedback suggestions on the "Catalog" view. +- ([Commercial feature][303]) In the web UI, reimplemented saved searches on the entity list view. +- ([Commercial feature][303]) In the web UI, fixed logic on the "Pipeline" edit form that previously caused the UI to crash +- ([Commercial feature][303]) In the web UI, fixed a XSS vulnerability in check result outputs +- ([Commercial feature][303]) In the web UI, removed erroneous links from edit page success messages + +## 6.9.0 release notes + +**November 1, 2022** — The latest release of Sensu Go, version 6.9.0, is now available for download. + +Sensu Go 6.9.0 provides a mix of new features, customer experience improvements, and bug fixes. The new CyberArk integration provides a new way to store your secrets, and Sensu also now supports metric tags in the Graphite plaintext protocol. Additionally, agent websocket connection log entries now include the backend name and authentication requests are now logged with their status. Under the hood, keepalive reconstructions no longer block backend startup — they now run gradually in the background — and we bumped the etcd version to 3.5.5. Last but not least, Sensu Go 6.9.0 implements a number of usability enhancements and bug fixes for the web UI. + +Read the [upgrade guide][1] to upgrade Sensu to version 6.9.0. + +**NEW FEATURES:** +- ([Commercial feature][303]) Sensu now supports [CyberArk Conjur for secrets management][305] with the [`CyberArkProvider`][304] external secrets provider. + +**IMPROVEMENTS:** + +- ([Commercial feature][303]) In the web UI, when an action is disabled based on a user's role-based access control (RBAC) permissions, the error message now explains that the issue is due to missing permissions. +- ([Commercial feature][303]) In the web UI, you can now completely hide the Sensu Catalog in the left navigation menu by setting the `disabled` attribute to true in the GlobalConfig `catalog` object. +- ([Commercial feature][303]) In the web UI, when a catalog search does not retrieve any results, the user will see a prompt to submit feedback to the Sensu team. +- ([Commercial feature][303]) Updated Sensu packaging to use 0755 permissions for `/var/cache/sensu/sensu-agent` instead of 0750. +- Agent websocket connection logging now includes backend entity name. +- The authentication module now logs successful (INFO) and unsuccessful (ERROR) login attempts. +- The Sensu agent now ingests Graphite Plaintext Protocol tags and converts them to Sensu metric points with tags. For example, Sensu will ingest the Graphite tag `my.series;tag1=value1 1 999999999` as a metric point with the name "my.series" and a "tag1": "value1" tag. +- Keepalive reconstruction now runs gradually in the background, which improves stability during backend startup. +- Upgraded etcd version from 3.5.4 to 3.5.5. + +**FIXES:** +- ([Commercial feature][303]) In the web UI, the built-in subscriptions search query on the Entities page is now properly constructed. +- ([Commercial feature][303]) In the web UI, the check detail page now indicates when Sensu could not fetch a dynamic runtime asset listed in the check definition. +- ([Commercial feature][303]) In the web UI, the mutation dialog now properly reports unauthorized errors. +- ([Commercial feature][303]) In the web UI, saved searches now must have unique names to prevent accidentally overwriting existing saved searches. +- Fixed an issue that prevented multi-expression, exclusive event filters set to `deny` from being evaluated properly. + +## 6.8.2 release notes + +**October 6, 2022** — The latest release of Sensu Go, version 6.8.2, is now available for download. + +Sensu Go 6.8.2 includes logging improvements with the addition of check names for failed check execution requests. We also added a label to events with a truncated check output and now automatically restart the agent on Windows platforms after failures. The 6.8.2 patch release also modifies the keepalive startup logic and fixes a number of web UI issues in the Entities and configuration resource pages. + +Read the [upgrade guide][1] to upgrade Sensu to version 6.8.2. + +**IMPROVEMENTS:** + +- When check output is truncated due to the [max_output_size][302] configuration, the events the check produces will include a `sensu.io/output_truncated_bytes` label. +- Agent log messages now include the check name when a check execution request fails. +- On Windows platforms, the Sensu Agent service now automatically restarts after failures. + +**FIXES:** + +- ([Commercial feature][295]) In the web UI, restored the silence function on the Entities page. +- ([Commercial feature][295]) In the web UI, resource pages now automatically refresh after creating resources. +- ([Commercial feature][295]) The web UI now displays pipeline definitions under the **RAW** tab on individual pipeline resource pages. +- ([Commercial feature][295]) In the web UI, corrected the link to the entity reference in the Edit Entity modal. +- ([Commercial feature][295]) In the web UI, errors displayed when deleting and re-adding an asset from asset page have been addressed. +- ([Commercial feature][295]) In the web UI, fixed the validation for resource names and array fields to prevent crashes. +- ([Commercial feature][295]) In the web UI, the configuration resource pages now show an empty list instead of an endless loading indicator for users who do not have the required permissions. +- ([Commercial feature][295]) In the web UI, fixed a bug that could cause a crash when an authorized user does not have an explicitly set username. +- ([Commercial feature][295]) In the web UI, temporarily disabled saved searches on Entity, Services, Silences, and Check pages. +- ([Commercial feature][295]) In the web UI, fixed a bug that prevented individual resource pages from displaying annotations and labels on initial page load. +- ([Commercial feature][295]) In the web UI, when users do not have the required permissions to perform a specific action, the action's button is now disabled with a tooltip to explain the reason. +- Modified keepalive startup so that etcd lease errors will not cause sensu-backend crashes. + +## 6.8.1 release notes + +**September 13, 2022** — The latest release of Sensu Go, version 6.8.1, is now available for download. + +Sensu Go 6.8.1 includes web UI fixes for OIDC refresh token expiry and information displayed on the Entities page, as well as a change in how check subdue begin and end times are evaluated. + +Read the [upgrade guide][1] to upgrade Sensu to version 6.8.1. + +**FIXES:** + +- ([Commercial feature][295]) In the web UI, OIDC refresh token requests now properly invoke the sign-in dialog instead of causing an `HTTP 404 Not Found` error. +- ([Commercial feature][295]) In the web UI, the entity list no longer displays the values of redacted labels. +- Check subdues are now evaluated as half-open intervals so that they are inclusive of the begin time and +1-second exclusive of the end time. Previously, subdue periods were evaluated as closed intervals and were exclusive of the begin and end times. This change prevents unintended gaps between subdues. + +## 6.8.0 release notes + +**August 29, 2022** — The latest release of Sensu Go, version 6.8.0, is now available for download. + +Sensu Go 6.8.0 delivers a mix of new features, valuable improvements, and helpful fixes. The new /ready API endpoint provides information about backend readiness, and the api-serve-wait-time and agent-serve-wait-time backend configuration options can help prevent instability during sensu-backend startup. The web UI now includes dedicated resource pages for assets, pipelines, role-based access control (RBAC) resources, and secrets. Plus, the resource pages now include details that give you more information about your resources at a glance. We've also fixed bugs that could cause backend crashes or result in incorrect event.check.issued values and improved prioritization to prevent keepalive event creation storms. + +Read the [upgrade guide][1] to upgrade Sensu to version 6.8.0. + +**NEW FEATURES:** + +- Added the [api-serve-wait-time][300] and [agent-serve-wait-time][301] backend configuration options. +Use api-serve-wait-time to delay serving API requests and agent-serve-wait-time to delay accepting agent connections after starting the backend. +- Added the [/ready API endpoint][299] to provide HTTP GET access to information about whether a Sensu instance is ready to serve API requests and accept agent connections. + +**IMPROVEMENTS:** + +- ([Commercial feature][295]) The web UI now includes [resource pages][297] for assets, pipelines, role-based access control (RBAC) resources, and secrets. +- ([Commercial feature][295]) In the web UI, resource pages now render resources in an infinite list, with a total row count provided at the bottom-right of the list. +- ([Commercial feature][295]) The resource pages in the web UI now display additional information about each resource, such as subscriptions, labels, API versions, and command attribute values. +- ([Commercial feature][295]) In the web UI, the [system information modal][296] now displays the name of the connected Sensu backend. +- Eventd now prioritizes keepalive events over other events to help prevent keepalive event creation storms and mass agent disconnects. + +**FIXES:** + +- ([Commercial feature][295]) When the [event.check.issued][298] attribute has a null value, the event detail page in the web UI now displays `N/A` instead of `December 31, 1969`. +- Fixed a bug that could cause a sensu-backend crash if the BackendIDGetter encountered etcd client unavailability. + +## 6.7.5 release notes + +**August 10, 2022** — The latest release of Sensu Go, version 6.7.5, is now available for download. + +Sensu Go 6.7.5 upgrades the graphql-go/graphql library to address [CVE-2022-37315][293] in which a malicious actor may craft a query that can crash the backend instance. + +Read the [upgrade guide][1] to upgrade Sensu to version 6.7.5. + +**IMPROVEMENTS** +- Upgraded graphql-go/graphql to remediate [CVE-2022-37315][293]. + +## 6.7.4 release notes + +**July 15, 2022** — The latest release of Sensu Go, version 6.7.4, is now available for download. + +Sensu Go 6.7.4 upgrades the Go version to 1.17.12. + +Read the [upgrade guide][1] to upgrade Sensu to version 6.7.4. + +**IMPROVEMENTS** +- Upgraded Go version from 1.17.6 to 1.17.12. + +## 6.7.3 release notes + +**July 7, 2022** — The latest release of Sensu Go, version 6.7.3, is now available for download. + +Sensu Go 6.7.3 includes fixes for the Sensu Catalog sort order and web UI notifications, as well a database issue that could cause backends to crash. +We also fixed bugs that affected business service monitoring (BSM) service components and removed limits on Active Directory (AD) and Lightweight Directory Access Protocol (LDAP) searches. +This patch release includes a change in how agents execute check requests to prevent `check execution still in progress` failures. + +Read the [upgrade guide][1] to upgrade Sensu to version 6.7.3. + +**IMPROVEMENTS** +- ([Commercial feature][268]) Added supported packages for the Sensu backend, Sensu agent, and sensuctl for RHEL 9. + +**FIXES** +- ([Commercial feature][268]) When using the business service monitoring (BSM) feature, service component metadata is now included in the [`check` scope][291] of events the service component generates. +Also fixed a bug that could cause BSM service component queries to retrieve events that do not match the specified query expressions. +- ([Commercial feature][268]) Removed a database constraint that could cause backends to crash when running agents on hosts that have many addresses associated with a single network interface. +- ([Commercial feature][268]) Active Directory (AD) and Lightweight Directory Access Protocol (LDAP) searches are no longer limited to 1000 results. +- ([Commercial feature][268]) In the web UI, [Sensu Catalog][269] integrations are now listed alphabetically. +- ([Commercial feature][268]) In the web UI's automated [Sensu Plus][271] setup dialog, the value in the **Source URL** field is no longer truncated. +- ([Commercial feature][268]) In the web UI, pop-up notifications at the bottom of the page are no longer obscured by other content. +- To prevent `check execution still in progress` failures, agents will no longer execute check requests with issued timestamps that are equal to or older than the issued timestamp for the last executed check request with the same check name. + +## 6.7.2 release notes + +**May 12, 2022** — The latest release of Sensu Go, version 6.7.2, is now available for download. + +Sensu Go 6.7.2 includes a fix for sensu-backend stability and adds an active poller for PostgreSQL config changes. +We've also improved the Sensu Plus modal in the web UI. + +Read the [upgrade guide][1] to upgrade Sensu to version 6.7.2. + +**IMPROVEMENTS** +- ([Commercial feature][268]) In the web UI, the Sensu Plus modal dialog now directs users who already have a Sumo Logic account to follow the instructions to manually set up Sensu Plus. +- ([Commercial feature][268]) In the web UI, the Sensu Plus post-setup modal dialog now indicates success when you use the Copy button to copy the Source URL. +- ([Commercial feature][268]) Added supported packages for the Sensu backend, Sensu agent, and sensuctl for Ubuntu 22.04. +- Added the etcd-unsafe-no-fsync backend configuration option, which makes it possible to run sensu-backend with an embedded etcd node for testing and development without placing too much load on the file system. +- Upgraded etcd version from 3.5.2 to 3.5.4. + +**FIXES** +- ([Commercial feature][268]) Fixed a bug that could cause a backend crash when pruning SumoLogicMetricsHandler and TCPStreamHandler resource types. +- ([Commercial feature][268]) Implemented an active poller for PostgreSQL configuration changes. +- The correct round robin scheduler source ("etcd" or "postgres") is now printed in events and logs. + + +## 6.7.1 release notes + +**April 28, 2022** — The latest release of Sensu Go, version 6.7.1, is now available for download. + +Sensu Go 6.7.1 delivers several improvements and fixes in the Sensu Catalog, along with an update to cron scheduler logging. We've also included fixes for data races in schedulerd and agentd. + +Read the [upgrade guide][1] to upgrade Sensu to version 6.7.1. + +**IMPROVEMENTS** +- ([Commercial feature][268]) Updated install button styling and improved text padding and margins for integration details and configuration dialog icons in the [Sensu Catalog][290]. +- ([Commercial feature][268]) In the [Sensu Catalog][290], the integrations list is now sorted alphabetically. +- The cron scheduler now logs that it is stopping before it begins the process of stopping. + +**FIXES** +- ([Commercial feature][268]) In the [Sensu Catalog][289], fixed an issue that prevented the overwrite function from properly overwriting existing resources. +- Fixed several data races in schedulerd. +- Mitigated a data race in agentd sessions. + +## 6.7.0 release notes + +**April 21, 2022** — The latest release of Sensu Go, version 6.7.0, is now available for download. + +Sensu Go 6.7.0 includes a number of new features, improvements and fixes, including Sensu Go's newest feature, the Sensu Catalog. The Catalog is a marketplace within the Sensu web UI that facilitates new user onboarding and deploying production-ready monitoring in minutes. Sensu Go 6.7.0 also includes metric threshold evaluation, keepalive pipelines, and check subdues. We've improved the onboarding workflow for Sensu Plus so you can seamlessly transmit Sensu observability data to Sumo Logic, added support for arrays of strings and objects in the `sensu.CheckDependencies` Sensu query expression, added an attribute to the GlobalConfig specification, and more. Bug fixes in Sensu Go 6.7.0 include adding pipelines within the event.check object, correcting TCP stream handler `max_connections` behavior, and detecting ARM platform accurately. + +Read the [upgrade guide][1] to upgrade Sensu to version 6.7.0. + +**NEW FEATURES:** + +- ([Commercial feature][268]) Added the [Sensu Catalog][269], an online marketplace for monitoring and observability integrations that allows you to find, configure, and install integrations directly from the Sensu [web UI][270]. +- Added [metric threshold evaluation][285] to provide real-time alerts based on the metrics your Sensu checks collect. +- Added the [`keepalive-pipelines`][276] agent configuration option, which allows you to specify [pipelines][275] for processing keepalive events. +- Added the check [`subdues` attribute][277], which you can use to schedule alert-free periods of time directly in check definitions. + +**IMPROVEMENTS:** + +- ([Commercial feature][268]) For [Sensu Plus][271] setup, Sensu now automatically creates a Sumo Logic account and configures an HTTP Logs & Metrics Source for customers who start the process from the Sensu [web UI][270]. +- ([Commercial feature][268]) Markdown formatting is now supported for the [signin_message][288] attribute value in the GlobalConfig specification. +- ([Commercial feature][268]) Added the [serialization_format][287] attribute to the GlobalConfig specification, which you can use to specify the default format for [resource definitions in the web UI][286] (YAML or JSON). +- ([Commercial feature][268]) Added the [license_expiry_reminder][294] attribute to the GlobalConfig specification, which you can use to specify the number of days before license expiration to begin displaying the license expiration banner in the web UI. +- ([Commercial feature][268]) [Business service monitoring (BSM)][281] now uses the PostgreSQL round robin Ring V2 implementation, even if the [`enable_round_robin`][280] attribute is set to `false` in the PostgresConfig definition. +- ([Commercial feature][268]) Added the `sensu_go_etcd_cluster_leases` metric to the backend [metrics log][282] to track the count of current etcd leases for debugging. +- ([Commercial feature][268]) Added logging for [TCP stream handler][283] events. +- The [`sensu.CheckDependencies`][284] Sensu query expression now supports arrays of strings and arrays of objects. +- On backend startup, Sensu now creates the [`sensu-system` namespace][279] and a [backend entity][278] to log secrets provider errors and help prevent spamming the event bus with backend events. +- For connections with faulty TLS configurations, error log entries now include a `source` property that lists the corresponding agent's IP address and port to identify which agent generated each log entry for troubleshooting. +- Increased the default values for the backend configuration options [etcd-election-timeout][272] (from 1000 to 3000) and [etcd-heartbeat-interval][273] (from 100 to 300). +- Upgraded etcd version from `3.5.0` to `3.5.2`. + +**FIXES:** + +- ([Commercial feature][268]) Fixed a bug that could cause pipeline resources to hang when using a [TCP stream handler][283] whose `max_connections` attribute is set to greater than zero. +- In events, event.check objects now include any pipelines specified in the check configuration. +- Socket handlers that are interrupted by an error mid-write will no longer cause a sensu-backend panic. +Also, socket handlers will now respect their timeout settings after the initial connection is established. +- Fixed a bug that prevented accurate ARM version detection for sensu-agent. + + +## 6.6.6 release notes + +**February 16, 2022** — The latest release of Sensu Go, version 6.6.6, is now available for download. + +Sensu Go 6.6.6 includes several web UI fixes for GraphQL queries. This patch release also contains fixes for the PostgreSQL event store, including improving retry logic when the event store is unavailable, as well as not reverting to etcd as a fallback event store. + +Read the [upgrade guide][1] to upgrade Sensu to version 6.6.6. + +**IMPROVEMENTS** +- ([Commercial feature][259]) In the web UI, added error type to GraphQL metrics to help track down slow queries. + +**FIXES** +- ([Commercial feature][259]) When the PostgreSQL provider is configured with ["strict: true"][267], the provider will attempt to connect to an unavailable PostgreSQL server indefinitely instead of reverting to etcd as an event store after three failed connection attempts. +- ([Commercial feature][259]) When the PostgreSQL provider is configured to use strict mode, the provider confirms whether the current user has `CREATE` privileges within the current schema, not the current database. +- ([Commercial feature][259]) The PostgreSQL provider now respects context cancellation and will fail immediately when users issue a termination signal. +- ([Commercial feature][259]) Fixed an issue where metrics would not be recorded when an error occurred. +- ([Commercial feature][259]) In the web UI, fixed an issue with GraphQL queries where an offset of >= 500 couldn't be used when paging through entities. + +## 6.6.5 release notes + +**February 3, 2022** — The latest release of Sensu Go, version 6.6.5, is now available for download. + +Sensu Go 6.6.5 includes several web UI improvements to reduce cluster load and adds a message to clarify web UI search results for the events and entities pages. This patch release also fixes bugs in round robin scheduling and the PostgreSQL configuration watcher and removes outdated language in an interactive-mode prompt for sensu-backend upgrade. + +Read the [upgrade guide][1] to upgrade Sensu to version 6.6.5. + +**IMPROVEMENTS** +- ([Commercial feature][259]) When using PostgreSQL, queries for multiple entity states are now more efficient. +- ([Commercial feature][259]) In the web UI, if a search reaches the [limit for the events or entities][266] page, the results count at the bottom-right corner of the page now indicates that the total number of matches exceeds the number of results listed. +- ([Commercial feature][259]) In the web UI, several changes help reduce cluster load: federated clusters now query remote clusters in parallel; GraphQL resolvers are no longer invoked if the query deadline has already been reached; and we improved the performance of GraphQL queries to the local cluster. + +**FIXES** +- ([Commercial feature][259]) Fixed a bug in round robin scheduling that could delay notification routing after creating or updating business service monitoring (BSM) service components. +- ([Commercial feature][259]) Fixed a bug in the PostgreSQL configuration watcher that could prevent bsmd from being reenabled after an update. +- ([Commercial feature][259]) In the web UI, fixed a bug that could result in graphql-go nullification of entity.status values greater than math.MaxInt32. +- Removed Sensu Go 5.x-specific language in the confirmation prompt for sensu-backend upgrade in interactive mode. +- Resolved unpredictable ringv2 behavior when identical subscriptions are created from different contexts. + +## 6.6.4 release notes + +**January 26, 2022** — The latest release of Sensu Go, version 6.6.4, is now available for download. + +Sensu Go 6.6.4 includes a number of bug fixes, security improvements, and a new metric, `sensu_go_event_metric_points_processed`. +Fixes in this patch release will help prevent backend crashes when PostgreSQL is taken offline and keep backend entity rows from filling up the entities table. +The 6.6.4 patch release also includes several improvements to further secure the web UI. + +Read the [upgrade guide][1] to upgrade Sensu to version 6.6.4. + +**IMPROVEMENTS** +- ([Commercial feature][259]) In the web UI, added the [X-Frame-Options][263] header to tell browsers the web application cannot be loaded within an iframe to prevent tailored click-jacking attacks. +- ([Commercial feature][259]) In the web UI, added the [HSTS header][264] if TLS has been configured to ensure that the browser loads the application and its requisite assets with a secure connection. +- ([Commercial feature][259]) In the web UI, added the [X-Content-Type-Options][265] nosniff header so that browsers respect the given Content-Type header when loading content referenced by a script tag. +- Added the `sensu_go_event_metric_points_processed` counter metric and included it in Tessen reporting. + +**FIXES** +- ([Commercial feature][259]) Fixed bugs in business service monitoring (BSM) and round robin scheduling to prevent missed check executions when PostgreSQL round robin scheduling is enabled. +- ([Commercial feature][259]) Fixed a bug that could cause sensu-backend to crash if PostgreSQL was taken offline and restarted. +- ([Commercial feature][259]) Fixed a bug that could cause ephemeral backend entity rows to fill up the entities table in PostgreSQL. +- ([Commercial feature][259]) BSM event selectors can no longer select events outside the service component namespace. +- ([Commercial feature][259]) In the web UI, fixed a bug the prevented HTTP requests from being properly cancelled after a context deadline (timeout) was exceeded. +- Fixed a bug that could cause the backend to crash if a pipeline references a non-existent handler. + +## 6.6.3 release notes + +**December 16, 2021** — The latest release of Sensu Go, version 6.6.3, is now available for download. + +Sensu Go 6.6.3 includes improvements to reduce load on clusters and support cluster recovery, as well as a backend configuration option for specifying the internal etcd client log level. Fixes in this patch release will help prevent backend crashes when keepalive leases are revoked and when the backend cannot write to the event log file. In addition, this patch fixes issues that could result in a leaked etcd lease and keep the backend from terminating correctly. + +Read the [upgrade guide][1] to upgrade Sensu to version 6.6.3. + +**IMPROVEMENTS** + +- ([Commercial feature][259]) In the web UI, the default polling interval on the [entities page][261] is now 30 seconds to help reduce load on clusters. Search results for entities are limited to the first 500 matching entities. Also, the web UI response time and memory usage is substantially improved when opening the entities page in the default state (loading the first page of results, with no search filter applied). +- ([Commercial feature][259]) In the web UI, for instances that use etcd for event storage, search results for events are limited to 25,000 matching events. +- Added the [`etcd-client-log-level`][262] configuration option for setting the log level of the etcd client used internally within sensu-backend. +- The agentd daemon now starts up after all other daemons, which improves cluster recovery after the loss of a backend. +- When using external etcd (the `no-embed-etcd` backend configuration option is set to `true`), sensu-backend now crashes when its daemons do not stop within 30 seconds, which can happen due to an intentional shutdown or when database unavailability triggers an internal restart. +When using embedded etcd, sensu-backend will still try to avoid crashing to prevent member corruption. + +**FIXES** + +- New agent sessions no longer result in a leaked etcd lease. +- sensu-backend now prints a warning and continues instead of crashing when it cannot write to the specified event-log-file. +- Fixed a bug that could cause a crash when keepalive leases are revoked on another backend or by an etcd operator. +- Fixed an issue that could prevent sensu-backend from terminating correctly. +- Proxy entity state is now created when it is missing and a matching entity config already exists. + +## 6.6.2 release notes + +**December 8, 2021** — The latest release of Sensu Go, version 6.6.2, is now available for download. + +The Sensu Go 6.6.2 patch release includes improvements in PostgreSQL health check queries and memory consumption for events and entities pages in the web UI. This release also fixes a web UI issue that provided incorrect links for cluster-wide resources. + +Read the [upgrade guide][1] to upgrade Sensu to version 6.6.2. + +**IMPROVEMENTS** + +- ([Commercial feature][259]) Changed the SQL operation for PostgreSQL health check queries to reduce query cost. +- ([Commercial feature][259]) In the web UI, removed **Related Entities** from individual pages for events and entities to eliminate the substantial memory consumption required to construct the list. + +**FIXES** + +- ([Commercial feature][259]) In the web UI, fixed an issue that provided incorrect links for cluster-wide resources. No web UI pages can show events across all namespaces. + +## 6.6.1 release notes + +**November 29, 2021** — The latest release of Sensu Go, version 6.6.1, is now available for download. + +This patch release removes a debugging log entry; adds cron library error information to validation errors for Check and CheckConfig resources; and fixes a web UI bug that expanded the clear silences dialog to the entire frame. In addition, Sensu now sets event timestamps when events are resolved via sensuctl or the web UI. + +Read the [upgrade guide][1] to upgrade Sensu to version 6.6.1. + +**IMPROVEMENTS** + +- To provide additional context, errors returned by the cron library are now included with the errors Sensu returns when validating Check and CheckConfig resources. +- Removed a debugging log entry that could cause logs to grow too big, too quickly. + +**FIXES** +- ([Commercial feature][259]) In the web UI, the dialog window for clearing silences no longer expands to the entire frame. +- Sensu now sets event timestamps when you resolve events with sensuctl or in the web UI. + +## 6.6.0 release notes + +**November 25, 2021** — The latest release of Sensu Go, version 6.6.0, is now available for download. + +This release introduces PostgreSQL event store sorting as well as web UI improvements like support for ANSI color codes and a warning message when editing resources on a cluster with an older version than the gateway cluster. Sensu Go 6.6.0 also adds a label to logged metrics to help identify the backend that generated the metrics, logs connection errors along with context errors, and fixes a bug that could cause a backend crash in case of etcd client unavailability. + +Read the [upgrade guide][1] to upgrade Sensu to version 6.6.0. + +**IMPROVEMENTS** +- ([Commercial feature][259]) The web UI color themes are updated, and the default theme now uses cyan for elements like the left navigaton menu and breadcrumb navigation text. +- ([Commercial feature][259]) In the web UI, users now receive a warning message when they try to add or edit resources on an cluster that is running an older Sensu backend version than the gateway cluster. +- ([Commercial feature][259]) The web UI now supports ANSI color codes, which improves check output readability when it includes color. +- ([Commercial feature][259]) Added support for sorting for the PostgreSQL event store. In addition, GraphQL can now use the PostgreSQL event store to sort events and get the total event count. +- Logged metrics now include a backend label. This makes it possible to associate metrics from the [metrics log][258] file with the backend they were generated on. +- Sensu no longer applies zero values for [etcd configuration options][260]. This prevents overwriting the etcd-provided default values with null, zero, slice, or empty values. + +**FIXES** +- When sensu-go cannot connect to etcd, the connection error is now logged along with context errors. +- Fixed a bug that could cause sensu-backend to crash if the BackendIDGetter encounters etcd client unavailability. + +## 6.5.5 release notes + +**November 22, 2021** — The latest release of Sensu Go, version 6.5.5, is now available for download. + +The Sensu Go 6.5.5 patch release adds two backend configuration options for configuring the API and web UI HTTP servers' write timeouts and three new GraphQL duration metrics for the metrics log. This release also delivers several bug fixes, including fixes for sensu-backend and sensu-agent panics and failed keepalive lease grant operations. + +Read the [upgrade guide][1] to upgrade Sensu to version 6.5.5. + +**IMPROVEMENTS** +- Added the [api-write-timeout][256] and [dashboard-write-timeout][257] backend configuration options. +These options allow you to configure the timeout for the respective HTTP servers' response writes, which is helpful when requests might take more than a few seconds to complete. +- Added graphql_duration_seconds, graphql_duration_seconds_sum, and graphql_duration_seconds_count to the [metrics log][238]. Also added objectives (0.5, 0.9, 0.99) to the graphql_duration_seconds metric. +- Added Prometheus metrics for tracking lease operations, with labels for operation type and status, and added sensu_go_lease_ops to the [metrics log][238]. + +**FIXES** +- Updated the assets, pipeline, and eventd duration metrics added in [Sensu Go 6.5.2][255] to use milliseconds for consistency with other duration metrics. +- Updated the /version API so that responses reflect the versions of external etcd clusters based on the first available etcd endpoint. +- Fixed a bug that could cause sensu-backend and sensu-agent to panic due to concurrent websocket writes. +- Sensu no longer logs an error when one side of a websocket tries to close a previously closed connection. +- Sensu now retries keepalive lease grant operations that fail due to rate limiting. + +## 6.5.4 release notes + +**October 30, 2021** — The latest release of Sensu Go, version 6.5.4, is now available for download. + +This patch releases and updates the sensu-go core/api module. + +Read the [upgrade guide][1] to upgrade Sensu to version 6.5.4. + +**FIXES** +- Released and updated the sensu-go core/api module. + +## 6.5.3 release notes + +**October 29, 2021** — The latest release of Sensu Go, version 6.5.3, is now available for download. + +This patch adds the 6.5.2 metrics to the metrics log, fixes bugs in validation for environment variables in JavaScript mutators and asset expansion error handling, and vendors the correct version of sensu-go. + +Read the [upgrade guide][1] to upgrade Sensu to version 6.5.3. + +**IMPROVEMENTS** + +- Added the [Sensu Go 6.5.2][255] eventd, pipeline, and asset metrics to the [metrics log][238] to facilitate troubleshooting. + +**FIXES** +- ([Commercial feature][229]) Vendored the correct version of sensu-go. +- Fixed a bug in API validation that rejected JavaScript mutators that use environment variables available in the environment rather than defined in the mutator env_vars attribute. +- Fixed a bug that prevented asset expansion errors from being handled. + +## 6.5.2 release notes + +**October 28, 2021** — The latest release of Sensu Go, version 6.5.2, is now available for download. + +The Sensu Go 6.5.2 patch release adds a number of metrics to provide more information about event handling and asset fetching and extraction. +In addition, this patch makes operating system environment variables accessible with JavaScript mutators and omits an extraneous attribute that appeared in web UI resource data. + +Read the [upgrade guide][1] to upgrade Sensu to version 6.5.2. + +**IMPROVEMENTS** + +- For JavaScript mutators, you can now list the names of any environment variables that are available in your environment (in addition to defining environment variables) in the [env_vars attribute][254]. +This allows you to transform events with metatdata from the Sensu environment, which is useful for downstream processing and filtering when sending Sensu event data for further processing. +- Added sensu_go_event_handler_duration_sum and sensu_go_event_handler_duration_count and added `status` and `event_type` labels to the sensu_go_event_handler_duration metric. +These updates allow you to determine whether an event was handled successfully. +- Added summary metrics for pipelined and pipeline operations to provide insight into how time is spent when pipelined and a pipeline resource handles an event: + - sensu_go_pipelined_message_handler_duration + - sensu_go_pipeline_duration + - sensu_go_pipeline_resolve_duration + - sensu_go_pipeline_filter_duration + - sensu_go_pipeline_mutator_duration + - sensu_go_pipeline_handler_duration +- Added summary metrics for eventd to provide insight into how time is spent when eventd handles an event: + - sensu_go_eventd_create_proxy_entity_duration + - sensu_go_eventd_update_event_duration + - sensu_go_eventd_bus_publish_duration + - sensu_go_eventd_liveness_factory_duration + - sensu_go_eventd_switches_alive_duration + - sensu_go_eventd_switches_bury_duration +- Added two metrics to provide insight into how time is spent when an asset is fetched and extracted: + - sensu_go_asset_fetch_duration + - sensu_go_asset_expand_duration + +**FIXES** + +- ([Commercial feature][229]) Fixes a bug in the web UI that added a `__virtual` attribute in the [resource data][249] for configuration resources. + +## 6.5.1 release notes + +**October 20, 2021** — The latest release of Sensu Go, version 6.5.1, is now available for download. + +This patch fixes several issues in the web UI and adds Prometheus counters for pipeline workflow handler processing. + +Read the [upgrade guide][1] to upgrade Sensu to version 6.5.1. + +**IMPROVEMENTS** + +- Added Prometheus counters for pipeline workflow handler processing: + - sensu_go_handler_requests: Number of processed handler requests + - sensu_go_handler_requests_total: Total number of handler requests invoked + +**FIXES** + +- ([Commercial feature][229]) Fixed a bug that could result in an error when listing entities with the PostgreSQL store enabled. +- ([Commercial feature][229]) In the web UI, fixed an issue with the native date and time picker that could cause problems when creating silences. +- ([Commercial feature][229]) In the web UI, fixed a bug that prevented users from editing service components. +- ([Commercial feature][229]) In the web UI, fixed the redirect for deleting entities so that it returns users to the Entities page rather than loading a 404 page for the deleted entity's details. + +## 6.5.0 release notes + +**October 13, 2021** — The latest release of Sensu Go, version 6.5.0, is now available for download. + +This release includes a number of improvements, specifically exciting new capabilities in the observability pipeline and a major simplification to how "pipelines" are configured. Sensu Go 6.5.0 introduces a new first-class `Pipeline` resource for defining logical pipeline workflows composed of filters + mutators + handlers. We're also introducing new streaming handler types: a TCPStreamHandler with TLS support and a SumoLogicMetricsHandler for seamless integration with the Sumo Logic Continuous Intelligence platform. Enhancements in the web UI include a completely overhauled configuration management system (with new views for the Checks, Filters, Handlers, and Mutators pages) and behind-the-scenes improvements that pave the way for even more new configuration management capabilities in future releases. Read the full release notes below for all the details! + +Read the [upgrade guide][1] to upgrade Sensu to version 6.5.0. + +**NEW FEATURES:** + +- ([Commercial feature][229]) Added [Sensu Plus][247], a built-in integration you can use to transmit your Sensu observability data to Sumo Logic via the Sumo Logic HTTP Logs and Metrics Source. +- ([Commercial feature][229]) Added support for [Sumo Logic metrics handlers][230] and [TCP stream handlers][231]. The [enterprise/pipeline/v1 API endpoints][232] provide HTTP access for retrieving and configuring Sumo Logic metrics handlers and TCP stream handlers. +- ([Commercial feature][229]) You can now [view resource data][249] for events, entities, and configuration resources like checks and handlers directly in the web UI. +- ([Commercial feature][229]) In the web UI, you can [execute individual checks on demand][250] either according to existing subscriptions or on specific agents by adding and removing subscriptions without making changes to the saved check subscriptions. +- ([Commercial feature][229]) Added Prometheus metrics for TCP stream handlers: + - sensu_go_tcp_stream_handler_events: Total number of events handled by the TCP stream handler + - sensu_go_tcp_stream_handler_errors: Total number of errors produced by the TCP stream handler + - sensu_go_tcp_stream_handler_latency: Distribution of handler latencies, in milliseconds, for the TCP stream handler + - sensu_go_tcp_stream_handler_connection_acquisition_latency: Distribution of connection acquisition latencies (how long it takes to acquire a connection from the connection pool), in milliseconds, within the TCP stream handler +- New [pipelines][233] resource allows you to specify event filters, mutators, and handlers in a single workflow instead of listing filters and mutators in handler definitions. You can reference pipelines in your check definitions. The [`/pipelines` API endpoint][234] provides HTTP access for retrieving pipeline data and configuring pipelines, and you can use [sensuctl][235] to manage pipelines. [Upgrade your Sensu agents][1] to Sensu Go 6.5.0 to use pipelines resources. +- [JavaScript mutators][246] are now available. JavaScript mutators are evaluated by the Otto JavaScript VM as JavaScript programs, which enables greater throughput at scale than pipe mutators. +- Check definitions now include the [pipelines attribute][236] for specifying pipeline resources to use for the check's observability events. +- Added [platform metrics logging][238] to log core Sensu metrics in InfluxDB Line Protocol format, along with the `disable-platform-metrics`, `platform-metrics-log-file`, and `platform-metrics-logging-interval` backend configuration options for managing the platform metrics logging feature. +- [Event logging][237] is no longer a commercial-only feature. +- You can now set sensuctl environment variables for a [single sensuctl command][243] or with [sensuctl configure][244]. + +**IMPROVEMENTS:** + +- Added environment variables `SENSU_BACKEND_ETCD_CLIENT_USERNAME` and `SENSU_BACKEND_ETCD_CLIENT_PASSWORD` for [connecting to external etcd via username and password authentication][245] instead of certificate authentication. There are no corresponding command line flags — these configuration options must be set via environment variables. +- You can now add an [API key][248] when you initialize the backend to make automated cluster setup and deployment more straightforward. +- Events now include the name of the agent that processed the event in the [`processed_by` attribute][251] to help you determine which agent processed an event executed by a proxy check request or a POST request to the events API. +- Added the [`ignore-already-initialized`][253] backend configuration option, which you can use to suppress the "already initialized" response and return an exit code 0 if a cluster has already been initialized. +- Upgraded Go version from 1.16.5 to 1.17.1. + +**SECURITY:** + +- Migrated [dgrijalva/jwt-go][239] to [golang-jwt/jwt][240] to address a vulnerability that would allow attackers to bypass intended access restrictions in situations. Read [CVE-2020-26160][241] for more information. + +**FIXES:** + +- Sensuctl env now properly lists `SENSU_API_KEY` and `SENSU_TIMEOUT` as options for [exporting environment variables][242]. In addition, sensuctl command exec now properly adds the `SENSU_API_KEY` and `SENSU_TIMEOUT` variables to the command's environment. +- Fixed a bug that could cause a crash when running the backend on darwin/arm64 and compressing a wrapped resource. +- Fixed a bug that could result in an etcd error if the number of silences in a given transaction exceeded etcd's default maximum number of operations per transaction. + +## 6.4.3 release notes + +**September 1, 2021** — The latest release of Sensu Go, version 6.4.3, is now available for download. + +This patch fixes a deadlock in the event log writer. + +Read the [upgrade guide][1] to upgrade Sensu to version 6.4.3. + +**FIXES:** + +- ([Commercial feature][215]) Fixed a bug that caused a deadlock in the [event log][228] writer. + +## 6.4.2 release notes + +**August 31, 2021** — The latest release of Sensu Go, version 6.4.2, is now available for download. + +This patch adds a backend configuration attribute that allows parallel event log encoding, as well as two summary metrics for the /metrics API endpoint. + +Read the [upgrade guide][1] to upgrade Sensu to version 6.4.2. + +**FIXES:** + +- ([Commercial feature][215]) Added the [`event-log-parallel-encoders`][226] backend configuration attribute, which allows you to indicate whether Sensu should use parallel JSON encoders for event logging instead of the default (a single JSON encoding worker). This fixes a bottleneck in the event logging feature. + +**IMPROVEMENTS:** + +- Added sensu_go_agentd_event_bytes and sensu_go_store_event_bytes summary metrics to the [/metrics API endpoint][227]. sensu_go_agentd_event_bytes tracks the sizes of events, in bytes, received by agentd on the backend. sensu_go_store_event_bytes tracks event sizes, in bytes, received by the etcd store on the backend. + +## 6.4.1 release notes + +**August 25, 2021** — The latest release of Sensu Go, version 6.4.1, is now available for download. + +This patch includes fixes that improve forward- and backward-compatibility for backends and prevent `sensuctl cluster member-list` crashes, as well as changes to the default log levels for webd, the API, and the sensu-agent. + +Read the [upgrade guide][1] to upgrade Sensu to version 6.4.1. + +**FIXES:** + +- ([Commercial feature][215]) For LDAP configurations, the `allowed_groups` attribute is omitted if not populated. +This change improves backend reliability with older versions of federation and sensuctl. +- Fixed a bug to prevent `sensuctl cluster member-list` crashes when the etcd response header is nil. +- Fixed a `sensu-backend init` regression that returned exit status 0 if the store was already initialized. +- Sensu Go OSS can now be built on darwin/arm64. + +**IMPROVEMENTS:** +- ([Commercial feature][215]) The default webd log level is now `warn`. +- The default log level for the Sensu API and [`sensu-agent`][225] is now `warn` (instead of `info`). +- The sensu-backend now reports when it is ready to process events at the `warn` level. +- You can now create resources with fields that are unknown to Sensu. +This change improves forward-compatibility with newer Sensu backends. + +## 6.4.0 release notes + +**June 28, 2021** — The latest release of Sensu Go, version 6.4.0, is now available for download. + +The latest release of Sensu Go, version 6.4.0, is now available for download. This release includes a number of feature improvements and important bug fixes. We upgraded the embedded etcd from version 3.3 to 3.5 for improved stability and security. The `sensu-backend init` command now supports a `wait` flag, which indicates that the backend should repeatedly try to establish a connection to etcd until it is successful -- fantastic news for Kubernetes users who want to bootstrap new Sensu Go clusters with external etcd! Check timeout also now works properly on Windows hosts: the Sensu Go agent can terminate check sub-processes on check execution timeout. This release fixes a bug that prevented deregistration events from working. There's something for everyone in this release! + +Read the [upgrade guide][1] to upgrade Sensu to version 6.4.0. + +**NEW FEATURES:** + +- ([Commercial feature][215]) In the web UI, the system information modal now includes license expiration information, accessed via the `CTRL .` keyboard shortcut, for users with the appropriate permissions. +- ([Commercial feature][215]) Added [page-specific configuration][221] options and a custom [sign-in message attribute][220] for the web UI. +- Added binary-only distribution for [macOS arm64][216]. + +**IMPROVEMENTS:** + +- Added [etcd-log-level][217] backend configuration option for setting the log level for the embedded etcd server. +- Added [`wait` flag][218] for the `sensu-backend init` command, which indicates the backend should repeatedly try to establish a connection to etcd until it is successful. +- The `timeout` flag for `sensu-backend init` is now treated as a duration instead of seconds (example duration format is `10s` for 10 seconds or `5m` for 5 minutes). +Values less than 1 second and integer values will be interpreted as seconds. +- Added `sensu_go_keepalives` Prometheus metric to count keepalive statuses over time and help identify instability due to keepalive failure. +- Upgraded Go version from `1.13.15` to `1.16.5`. +- Upgraded etcd version from `3.3.22` to `3.5.0`. +As a result, **6.4.0 is not backward-compatible with previous Sensu versions**. +Read the [upgrade instructions][222] for details about creating a full etcd database backup before you upgrade to Sensu Go 6.4.0. +Also, in etcd 3.5, some Prometheus metric names changed. +Read the [etcd documentation][219] for details. + +**FIXES:** + +- ([Commercial feature][215]) Selector statements that begin with quotes no longer cause an error if they follow the `&&` operator. +- ([Commercial feature][215]) Fixed a bug that allowed PostgresConfig resources to include a namespace attribute. +Also, invalid PostgresConfig resources can no longer be created. +- Fixed a bug that resulted in OK keepalive status after shutting down the agent. +- Fixed a bug in role-based access control (RBAC) that caused incorrect HTTP API statuses and web UI crashes when role bindings referred to missing roles. +The API now returns status `403` with a message to explain that the referenced role is missing. +- Fixed a bug that prevented deregistration events from validating due to empty `event.check.subscriptions` arrays. +- Fixed a bug that caused Windows agents to handle command timeouts improperly. + +## 6.3.0 release notes + +**May 26, 2021** — The latest release of Sensu Go, version 6.3.0, is now available for download. + +This release includes several new features, enhancements, bug fixes, and usability improvements. Construct a top-level business service-centric view for distributed infrastructure and applications with a preview of Business Service Monitoring! Rate-limit Sensu Go agent transport connections without using a separate load balancer. Use an API key to authenticate sensuctl, which is handy when automating Sensu Go configuration (for example CI pipelines) and other actions (like ad hoc check execution requests). The 6.3.0 release also improves the PostgreSQL store batching capabilities, raising the event processing throughput ceiling for most deployments. Check out the release notes below for more details — there's so much to love about this release! + +Read the [upgrade guide][1] to upgrade Sensu to version 6.3.0. + +**NEW FEATURES:** + +- ([Commercial feature][207]) Added [business service monitoring (BSM)][210] to provide high-level visibility into the current health of any number of business services, with a [built-in aggregate check rule template][211]. +- ([Commercial feature][207]) Added support for agent transport rate limiting via [`agent-burst-limit`][208] and [`agent-rate-limit`][209] backend configuration options. +- ([Commercial feature][207]) Added the `event-log-buffer-wait` backend configuration option, which allows you to specify how long the event logger will wait for the writer to consume events from the buffer when the buffer is full. +- Added the entity class [service][213], which represents a business service for the business service monitoring (BSM) feature. + +**IMPROVEMENTS:** + +- ([Commercial feature][207]) The [agent transport health API endpoint][212] repsonse now includes PostgreSQL health information. +- ([Commercial feature][207]) Added the [`poll_interval` default preferences][223] attribute to the `GlobalConfig` resource so administrators can adjust how often the web UI pages poll for new data. +- ([Commercial feature][207]) In the web UI, some form fields now include examples of valid values. +- Added the `--api-key` [global flag][214] for sensuctl commands. Use this flag with sensuctl commands to bypass username/password authentication. +- Logs for JavaScript filter evaluation errors now include more context. +- Concatenated YAML files now support carriage return and line feed (CRLF). +- Removed extraneous shell auto-completion suggestions for sensuctl. + +**FIXES:** + +- ([Commercial feature][207]) Migrated the PostgreSQL event store from github.com/lib/pq to github.com/jackc/pgx so that PostgreSQL batching works properly. +- ([Commercial feature][207]) In the web UI, error messages are now visible in dark mode. +- Fixed a bug that could cause the scheduler to crash when using round robin checks. +- Fixed a bug that calculated build information for every keepalive in OSS builds. +- SIGHUP no longer triggers an internal restart. + +## 6.2.7 release notes + +**April 1, 2021** — The latest release of Sensu Go, version 6.2.7, is now available for download. + +This patch includes fixes for potential deadlocks in metricsd and agentd and crashes in the scheduler and tessend as well as for a bug that calculated build information for every keepalive. + +Read the [upgrade guide][1] to upgrade Sensu to version 6.2.7. + +**FIXES:** + +- ([Commercial feature][193]) Fixed a potential deadlock in metricsd that could occur when performing an +internal restart. +- Fixed a potential deadlock in agentd due to the unit test timing out in the build pipeline. +- Fixed a bug that could cause the scheduler to crash when using round robin checks. +- Fixed a bug that calculated build information for every keepalive in OSS builds. +- Fixed a potential crash in tessend that could occur if the `ringv2.Event.Value` has a zero length. +- Fixed a bug that allowed some etcd watchers to try to process watch events that contain invalid pointers. + +## 6.2.6 release notes + +**March 25, 2021** — The latest release of Sensu Go, version 6.2.6, is now available for download. + +This patch fixes a bug that allowed PostgreSQL round robin scheduling to use a separate PostgreSQL connection for each subscription and improves the validation for POST/PUT requests for enterprise API endpoints. + +Read the [upgrade guide][1] to upgrade Sensu to version 6.2.6. + +**FIXES:** + +- ([Commercial feature][193]) Fixed a bug that allowed PostgreSQL round robin scheduling to use a separate PostgreSQL connection for each subscription. PostgreSQL round robin scheduling now uses exactly one extra PostgreSQL connection. +- ([Commercial feature][193]) Improved the validation for POST/PUT requests for enterprise API endpoints. Sensu now checks the type and namespace in the request body against the type and namespace in the request URL. + +## 6.2.5 release notes + +**February 2, 2021** — The latest release of Sensu Go, version 6.2.5, is now available for download. + +This patch fixes a bug regarding the event occurrences_watermark property. +This bug interfered with the property's expected behavior when using event filters like the popular fatigue check filter. + +Read the [upgrade guide][1] to upgrade Sensu to version 6.2.5. + +**FIXES:** + +- ([Commercial feature][193]) Fixed a bug that prevented occurrences_watermark from incrementing for non-zero events when using the PostgreSQL datastore. + +## 6.2.4 release notes + +**January 28, 2021** — The latest release of Sensu Go, version 6.2.4, is now available for download. + +This patch fixes a bug that prevented `federation/v1.Cluster` from appearing in the response for `sensuctl describe-type all` and resolves a web UI performance issue for PostgreSQL users. + +Read the [upgrade guide][1] to upgrade Sensu to version 6.2.4. + +**FIXES:** + +- ([Commercial feature][193]) `federation/v1.Cluster` now appears in the `sensuctl describe-type all` response. +- ([Commercial feature][193]) Fixed a performance issue that affected the web UI when using the PostgreSQL datastore. + +## 6.2.3 release notes + +**January 21, 2021** — The latest release of Sensu Go, version 6.2.3, is now available for download. + +This patch fixes two bugs: one that could prevent the `agent-managed-entity` configuration option from working properly and one that caused `sensuctl dump` output to include events from all namepaces rather than the specified namespace. + +Read the [upgrade guide][1] to upgrade Sensu to version 6.2.3. + +**FIXES:** + +- Fixed a bug that prevented the [agent-managed-entity][203] configuration attribute from working properly when no labels are defined. +- Fixed a bug where `sensuctl dump` output included events from all namespaces the user had access permissions for rather than events from only the specified namespace. + +## 6.2.2 release notes + +**January 14, 2021** — The latest release of Sensu Go, version 6.2.2, is now available for download. + +This patch fixes bugs that prevented PostgreSQL round robin scheduling from working properly. + +Read the [upgrade guide][1] to upgrade Sensu to version 6.2.2. + +**FIXES:** + +- ([Commercial feature][193]) Fixed a bug that could improperly enable PostgreSQL round robin scheduling after creating a PostgreSQL configuration. +- ([Commercial feature][193]) Fixed a bug that prevented PostgreSQL round robin scheduling if the namespace and check names were more than 63 characters long, combined. + +## 6.2.1 release notes + +**January 11, 2021** — The latest release of Sensu Go, version 6.2.1, is now available for download. + +This patch fixes bugs that could prevent users from enabling PostgreSQL after upgrading from 5.x or configuring agent labels and annotations with flags. In addition, `sensuctl prune hook` and `sensuctl prune check` now work as expected and users can no longer edit agent-managed entities in the web UI. + +Read the [upgrade guide][1] to upgrade Sensu to version 6.2.1. + +**FIXES:** + +- ([Commercial feature][193]) Fixed a bug that prevented users from enabling PostgreSQL as the event store after upgrading from 5.x. +- ([Commercial feature][193]) The `sensuctl prune hook` and `sensuctl prune check` subcommands now work as expected. +- ([Commercial feature][193]) In the web UI, fixed a bug that allowed users to edit Sensu [agent-managed entities][204]. +- Fixed a bug that generated a small amount of extra etcd or PostgreSQL traffic upon keepalive failure. +- In silenced entries, the `expire` field now represents the configured number of seconds until the entry should be deleted rather than the entry's remaining duration. +- Labels and annotations are now [configuration options][205] for sensu-agent. + +## 6.2.0 release notes + +**December 17, 2020** — The latest release of Sensu Go, version 6.2.0, is now available for download. + +The latest release of Sensu Go, version 6.2.0, is now available for download! Sensu Go 5.x and configuration management users rejoice: this release adds support for agent local configuration (that is, agent.yml) managed entities! Agent entities may now be managed exclusively by their agents when `sensu-agent` is started with the new `agent-managed-entity` configuration option. This makes it more straightforward to migrate from Sensu Go 5.x to 6.x, as existing agent entity management workflows like Puppet will just work with the new option enabled! Note that you will not be able to edit agent-managed entities via the backend REST API or web UI. + +Sensu Go 6.2.0 includes significant feature enhancements such as PostgreSQL backend round robin check scheduling for increased reliability and consistency, an updated format for silenced entry dates and durations in sensuctl tabular-format output, and a /health API endpoint for agent WebSocket transport status. This release delivers important bug fixes like consistently using `event_id` in logs and eliminating the sensuctl error when Vault provider SSL certificates do not exist on the local system. Also, enterprise/prune/v1alpha no longer requires cluster-wide permissions; users with limited permissions can put it to use in their namespaces! + +Read the [upgrade guide][1] to upgrade Sensu to version 6.2.0. + +**NEW FEATURES:** + +- ([Commercial feature][193]) Added support for the `memberof` attribute for the [LDAP authentication provider][199]. +- ([Commercial feature][193]) Added the ability to exclude resource types when using sensuctl prune with the [--omit flag][200]. +- ([Commercial feature][193]) Added support for [round robin scheduling on PostgreSQL][201] instead of etcd. +- ([Commercial feature][193]) Added support for OIDC authentication via [sensuctl configure][202]. +- Entities may now be [managed exclusively by their agents][204] when sensu-agent is started with the [agent-managed-entity][203] configuration attribute. +- The [/metrics API endpoint][196] now exposes build information as a Prometheus metric. +- Added /health API endpoint to agent WebSocket transport. +- Checks now include the [`scheduler` attribute][197], which Sensu automatically populates with the type of scheduler that schedules the check. +- Events now include the [`sequence` attribute][198], which the Sensu agent automatically sets at startup and increments by 1 at every successive check execution or keepalive event. +- Added support for using environment variables to define the configuration file paths for the Sensu agent (`SENSU_CONFIG_FILE`) and backend (`SENSU_BACKEND_CONFIG_FILE`). + +**IMPROVEMENTS:** + +- ([Commercial feature][193]) Refactored entity limiter to ensure that warning messages about approaching a license's entity or entity class limit are now only displayed for users with `create` or `update` permissions for the license. +- ([Commercial feature][193]) The [enterprise/prune/v1alpha API] endpoints[194] and the [sensuctl interface][195] now require less-broad permissions. +- Adjusted the format for silenced entry dates and durations in sensuctl tabular-format output. For all silenced entries, the begin date is now listed in RFC 3339 format. For silenced entries that have not begun, the list displays the expiration date in RFC 3339 format. For silenced entires with no expiration date, the list displays `-1`. For silenced entries that have begun, the list displays the duration (for example, 1m30s). +- Sensuctl and sensu-backend now ask users to retype their passwords when creating a new password in interactive mode. + +**FIXES:** + +- ([Commercial feature][193]) Sensuctl no longer produces an error when SSL certificates for the Vault provider do not exist on the local system. +- Logs now consistently use `event_id` rather than `event_uuid`. +- Sensuctl commands that only contain subcommands now exit with status code 46 when no arguments or incorrect arguments are given. +- The sensuctl dump command now includes a description. +- Sensuctl command descriptions now have consistent capitalization. +- Use of the `config-file` flag is no longer order-dependent. + +## 6.1.4 release notes + +**December 16, 2020** — The latest release of Sensu Go, version 6.1.4, is now available for download. + +This patch fixes a bug that could cause a crash in the backend API, addresses a case where agents do not honor HTTP proxy environment variables, and improves the error message reported by the agent when asset checksums do not match expectations. + +Read the [upgrade guide][1] to upgrade Sensu to version 6.1.4. + +**FIXES:** + +- Fixed a bug that could cause a panic in the backend core/v2/entities API. +- The agent asset fetching mechanism now respects HTTP proxy environment variables when `trusted-ca-file` is configured. +- When an asset artifact retrieved by the agent does not match the expected checksum, the logged error now includes the size of the retrieved artifact and more clearly identifies the expected and actual checksums. + +## 6.1.3 release notes + +**November 9, 2020** — The latest release of Sensu Go, version 6.1.3, is now available for download. + +This patch fixes a bug that caused event updates to fail with an error about a null value in the occurrences column. +This bug only affects Sensu instances that use PostgreSQL as the event store. + +Read the [upgrade guide][1] to upgrade Sensu to version 6.1.3. + +**FIXES:** + +- ([Commercial feature][172]) For instances that use PostgreSQL as the event store, fixed a bug that caused event updates to fail with an error message about a null value in the occurrences column. + + +## 6.1.2 release notes + +**October 28, 2020** — The latest release of Sensu Go, version 6.1.2, is now available for download. + +This patch release resolves a backend and agent crash related to JavaScript execution. + +Read the [upgrade guide][1] to upgrade Sensu to version 6.1.2. + +**FIXES:** + +- Fixed a bug related to JavaScript execution that could cause a crash in the backend and agent. + + +## 6.1.1 release notes + +**October 22, 2020** — The latest release of Sensu Go, version 6.1.1, is now available for download. + +This patch release includes a number of bug fixes that affect proper hook handling with `sensuctl prune` and `sensuctl dump`, entity creation via `sensuctl create`, form validation for subscription names in the web UI, and permissions for PATCH requests, among other fixes. + +Read the [upgrade guide][1] to upgrade Sensu to version 6.1.1. + +**FIXES:** + +- ([Commercial feature][172]) [`sensuctl prune`][192] now properly handles hooks when pruning resources. +- ([Commercial feature][172]) Fixed a bug that returned incorrect `!=` results for label selectors when no labels were defined. +- ([Commercial feature][172]) In the web UI, fixed a bug that could cause a GraphQL `no claims` error when a user's access token was no longer valid instead of displaying the sign-out dialog window. +- ([Commercial feature][172]) In the web UI, form validation for subscription names now matches allowed values. +- Fixed a bug that prevented sensu-agent from shutting down correctly. +- Entities are now properly created using `sensuctl create`. +- Per-entity subscriptions now persist with PATCH requests. +- Any user with [`update` permissions][190] for a resource can now make PATCH requests for that resource. +- HookConfig can now be exported via [`sensuctl dump`][191]. Also, `sensuctl dump` now properly logs API errors. +- eventd errors now include additional context for debugging. + + +## 6.1.0 release notes + +**October 5, 2020** — The latest release of Sensu Go, version 6.1.0, is now available for download. + +This release delivers significant performance and stability gains, feature enhancements, and several bug fixes. The web UI is now much snappier, and its search is redesigned with an improved syntax and suggestions! Monitor even more services and infrastructure when using the PostgreSQL store: batched Sensu event writes and improved indexing allows a single Sensu Go deployment to process and query more data than ever before. If you're using Prometheus client libraries to instrument your applications, the Sensu Go agent can now scrape and enrich those metrics! And if you're collecting metrics in other formats like Nagios PerfData, you can use the new output metric tags feature to enrich those metrics too! The sensuctl prune command also received some love, and it now loads and prunes configuration resources from multiple files! + +Read the [upgrade guide][1] to upgrade Sensu to version 6.1.0. + +**NEW FEATURES:** + +- ([Commercial feature][172]) Added support for custom secrets engine paths in [Vault secrets][175]. +- ([Commercial feature][172]) In the web UI, added [new search functionality][178], with improved syntax and suggestions. +- ([Commercial feature][172]) Added [`strict` attribute][179] to the PostgresConfig type to help debug incorrect configurations and database permissions. +- ([Commercial feature][172]) Added [`batch_buffer`, `batch_size`, and `batch_workers` attributes][181] to the PostgresConfig type so operators can optimize PostgreSQL latency and throughput. +- ([Commercial feature][172]) Added TLS configuration to the cluster resource so you can specify additional CA certificates and insecure mode. +- ([Commercial feature][172]) Added a `types` query parameter for listing [authentication providers][176] and [secrets providers][177] via the API. +- ([Commercial feature][172]) Added the [Sensu SaltStack Enterprise Handler][183] for launching +SaltStack Enterprise Jobs for automated remediation. +- ([Commercial feature][172]) The Alpine-based Docker image now has multi-architecture support with support for the linux/386, linux/amd64, linux/arm64, linux/arm/v6, linux/arm/v7, linux/ppc64le, and linux/s390x platforms. +- The backend configuration option [`api-request-limit`][173] is now available to configure the maximum API request body size (in bytes). +- In the [REST API][174], most configuration resources now support the PATCH method for making updates. +- Added new handler and check plugins: [Sensu Go Elasticsearch Handler][184], [Sensu Rundeck Handler][185], and [Sensu Kubernetes Events Check][186]. + +**IMPROVEMENTS:** + +- ([Commercial feature][172]) Improved logging for OIDC authentication providers. Also added [`disable_offline_access` OIDC spec attribute][180], which provides a workaround for authorization servers that do not support the `offline_access` scope. +- ([Commercial feature][172]) Added indexed field and label selectors to the PostgreSQL event store to improve performance for PostgreSQL event store queries with field and label selectors. +- Added Prometheus transformer for extracting metrics from check output using the Prometheus Exposition Text Format. +- Added the [`output_metric_tags` attribute][182] for checks so you can apply custom tags to enrich metric points produced by check output metric extraction. +- A warning is now logged when you request a dynamic runtime asset that does not exist. +- The trusted CA file is now used for agent, backend, and sensuctl asset retrieval. +- Per-entity subscriptions (such as `entity:entityName`) are always available for agent entities, even you remove subscriptions via the core/v2/entities API endpoints. +- Updated the [Sensu TimescaleDB Handler][187] to write tags as a JSON object instead of an array of objects, which facilitates tags queries. +- Updated the [Sensu Go Data Source for Grafana][188] plugin to support using API keys, fetching resources from all namespaces, using Sensu's built-in resposne filtering, grouping aggregation results by attribute, and number of [other improvements][189]. + +**FIXES:** + +- ([Commercial feature][172]) Fixed a bug in `sensuctl dump` that allowed polymorphic resources (e.g., secrets providers and authentication providers) to dump other providers of the same type. +- ([Commercial feature][172]) Check output is no longer truncated in the event log file when the max output size is set and the PostgreSQL event store is enabled. +- ([Commercial feature][172]) Sensuctl prune now handles multi-file/multi-url input correctly. +- ([Commercial feature][172]) Fixed a bug where PostgreSQL errors could cause the backend to panic. +- ([Commercial feature][172]) Fixed a bug where PostgreSQL would refuse to store event with a negative check status. +- The backend will no longer start if the web UI TLS configuration is not fully specified. +- The agent entity is now included in data passed to the stdin for the command process. +- Improved check scheduling to prevent stale proxy entity data when using cron or round robin schedulers. +- Fixed a bug that resulted in incorrect entity listings for agent entities created via the API instead of sensu-agent. +- When downloading assets, Sensu now closes the response body after reading from it. +- Fixed a crash in the backend and agent related to JavaScript execution. + +## 6.0.0 release notes + +**August 10, 2020** — The latest release of Sensu Go, version 6.0.0, is now available for download. + +With Sensu Go 6.0.0, you can control everything through the API. You can still use configuration management tools to bootstrap agent entities, but you don't need to! Our new agent entity management feature via the backend configuration API nearly eliminates the need for external (or out-of-band) configuration management for Sensu, which allows you to manage agent entity subscriptions and automate the discovery of system facts without updating agent local configuration files. Run a sensuctl command, click a button in the web UI, or execute a custom check plugin! + +Read the [upgrade guide][1] to upgrade Sensu to version 6.0.0. + +**BREAKING CHANGES FOR SENSU 6.0:** + +- The database schema for entities has changed. +As a result, after you complete the steps to [upgrade to Sensu 6.0][170] (including running the `sensu-backend upgrade` command), you will not be able to use your database with older versions of Sensu. +- For Sensu Go instances [built from source][164], the web UI is now a [standalone product][163] — it is no longer included with the Sensu backend. +Visit the [Sensu Go Web repository][163] for more information. +- After initial creation, you cannot change your [`sensu-agent` entity configuration][171] by modifying the agent's configuration file. + +**NEW FEATURES:** + +- ([Commercial feature][162]) Sensu now logs a warning when secrets cannot be sent to an agent because mTLS is not enabled. +- ([Commercial feature][162]) Added [JavaScript functions][169] `sensu.EventStatus`, `sensu.FetchEvent`, and `sensu.ListEvents` to the filter execution environment so you can now query the Sensu event store for other events within the filter namespace. +- ([Commercial feature][162]) Docker-only Sensu now binds to the hostname of containers instead of `localhost`. Docker images now set their own default values for environment variables `SENSU_AGENT_API_URL`, `SENSU_BACKEND_API_URL`, `SENSU_BACKEND_ETCD_INITIAL_CLUSTER`, `SENSU_BACKEND_ETCD_ADVERTISE_CLUSTER`, `SENSU_BACKEND_ETCD_INITIAL_ADVERTISE_PEER_URLS`, `SENSU_BACKEND_ETCD_LISTEN_CLIENT_URLS`, and `ETCD_LISTEN_PEER_URLS`. +- ([Commercial feature][162]) Added Linux packages for 386; armv5, armv6, and armv7; MIPS hard float, MIPS LE hard float, and MIPS 64 LE hard float; ppc64le; and s390x architectures. +Review the [supported platforms][165] page for a complete list of Sensu's supported platforms. +- ([Commercial feature][162]) Added [Sensu query expression][168] `sensu.CheckDependencies`. +- Added [binary-only distributions][164] for FreeBSD `armv5`, `armv6`, and `armv7` and Linux `ppc64le` and `s390x`. +- Added the `is_silenced` Boolean attribute to the event.Check object to indicate whether the event was silenced at the time it was processed. + +**IMPROVEMENTS:** + +- ([Commercial feature][162]) Added support for the `memberOf` attribute in Active Directory (AD). +- ([Commercial feature][162]) Added more descriptive information for errors in the federated web UI. +- The `dead` and `handleUpdate` methods in keepalived now use `EntityConfig` and `EntityState` respectively. +- The `dead()` and `createProxyEntity()` methods in eventd now use `corev3.EntityConfig` and `corev3.EntityState`. +- Agent entity updates now ignore state-related fields. +- You can now manage Sensu agent configuration via the HTTP API. +- For sysvinit services, Sensu now passes users' secondary groups (that is, groups other than the Sensu user group) to `chroot`, which gives the Sensu agent and backend access to the file access writes that are granted to the secondary groups. +- Output of `sensuctl asset add` now includes help for using the runtime asset. +- For role bindings and cluster role bindings, [`subjects.name`][166] values can now include unicode characters, and [`roleRef.type`][167] and [`subjects.type`][166] values are now automatically capitalized. +- Improved logging for the agent WebSocket connection. +- Improved the wording of the secret provider error message. +- Fewer keys in etcd are now stored for agents. +- Keepalive and round robin scheduling leases are now dealt with more efficiently. +- Upgraded Go version from 1.13.7 to 1.13.15. +- Upgraded etcd version from 3.3.17 to 3.3.22. + +**FIXES:** + +- ([Commercial feature][162]) Label selectors now work as expected with multiple requirements for events. +- ([Commercial feature][162]) Fixed an issue that prevented broken secrets providers from surfacing their errors. +- ([Commercial feature][162]) Fixed a bug for PostgreSQL datastores that could prevent GraphQL from retrieving all pages when fetching events in a namespace with more than 1000 total events, resulting in an unexpected error. +- ([Commercial feature][162]) Fixed a bug that could cause the backend to panic in case of PostgreSQL errors. +- Sensu now logs and returns and error if it cannot find a mutator. +- Errors produced in the agent by assets, check validation, token substitution, and event unmarshaling are logged once again. +- The User-Agent header is now set only upon on new client creation rather than upon each request. +- When the Sensu agent cannot parse the proper CA certificate path, Sensu logs this in the error message. +- Fixed a bug where highly concurrent event filtering could result in a panic. +- Fixed a bug where nil labels or annotations in an event filtering context would require you to explicitly check whether the annotations or labels are undefined. +With this fix, labels and annotations are always defined (although they may be empty). +- Fixed the log entry field for the check's name in schedulerd. + +## 5.21.5 release notes + +**March 25, 2021** — The latest release of Sensu Go, version 5.21.5, is now available for download. + +The Sensu 5.21.5 patch release improves the validation for POST/PUT requests for enterprise API endpoints. + +Read the [upgrade guide][1] to upgrade Sensu to version 5.21.5. + +**FIXES:** + +- ([Commercial feature][158]) Improved the validation for POST/PUT requests for enterprise API endpoints. Sensu now checks the type and namespace in the request body against the type and namespace in the request URL. + +## 5.21.4 release notes + +**March 9, 2021** — The latest release of Sensu Go, version 5.21.4, is now available for download. + +This patch release fixes a bug that caused the SIGHUP signal to restart the sensu-backend. + +Read the [upgrade guide][1] to upgrade Sensu to version 5.21.4. + +**FIXES:** + +- Fixed a bug that caused the SIGHUP signal used for [log rotation][206] to restart the sensu-backend. + +## 5.21.3 release notes + +**October 14, 2020** — The latest release of Sensu Go 5, version 5.21.3, is now available for download. + +This patch release includes a few fixes to improve stability and correctness. + +Read the [upgrade guide][1] to upgrade Sensu to version 5.21.3. + +**FIXES:** + +- Fixed a bug where HTTP connections could be left open after downloading assets. +- Fixed a bug where event filter or asset filter execution could cause a crash. +- ([Commercial feature][158]) Fixed a bug where PostgreSQL would refuse to store event with a negative check status. + +## 5.21.2 release notes + +**August 31, 2020** — The latest release of Sensu Go, version 5.21.2, is now available for download. + +This patch release includes two fixes: one for PostgreSQL errors that could cause the backend to panic and one to ensure that failed check events are written to the event log file. + +Read the [upgrade guide][1] to upgrade Sensu to version 5.21.2. + +**FIXES:** + +- ([Commercial feature][158]) Fixed a bug where PostgreSQL errors could cause the backend to panic. +- Failed check events are now written to the event log file. + +## 5.21.1 release notes + +**August 5, 2020** — The latest release of Sensu Go, version 5.21.1, is now available for download. + +This patch release includes fixes for a web UI crash when interacting with namespaces that contain 1000 or more events and regressions in logging various agent errors as well as an enhancement that provides additional context to WebSocket connection errors logged by the backend. + +Read the [upgrade guide][1] to upgrade Sensu to version 5.21.1. + +**IMPROVEMENTS:** + +- Backend log messages related to connection errors on the agent WebSocket API now provide more context about the error. + +**FIXES:** + +- Fixed a potential web UI crash when fetching events in namespace with 1000 or more events. +- Fixed a regression that prevented errors produced in the agent by assets, check validation, token substitution, or event unmarshaling from being logged. + +## 5.21.0 release notes + +**June 15, 2020** — The latest release of Sensu Go, version 5.21.0, is now available for download. + +The latest release of Sensu Go, version 5.21.0, is now available for download! This release delivers several enhancements and fixes. The most significant enhancements involve user management: you can now generate a password hash, specify the resulting hash in your user definitions without having to store cleartext passwords, and create and update these users using `sensuctl create`. You can also reset user passwords via the backend API. We also tuned Sensu Go agent logging and changed the default log level from warning to info. Plus, we crushed a number of nasty bugs: checks configured with missing hooks can no longer crash the agent, proxy check request errors do not block scheduling for other entities, and more! + +Read the [upgrade guide][1] to upgrade Sensu to version 5.21.0. + +**NEW FEATURES:** + +- ([Commercial feature][158]) Added [entity count and limit][156] for each entity class in the tabular title in the response for `sensuctl license info` (in addition to the total entity count and limit). +- ([Commercial feature][158]) Added Linux amd64 OpenSSL-linked binaries for the Sensu agent and backend, with accompanying `require-fips` and `require-openssl` configuration options for the [agent][161] and [backend][160]. +- Added `sensuctl user hash-password` command to generate password hashes. +- Added the ability to reset passwords via the backend API and `sensuctl user reset-password`. + +**IMPROVEMENTS:** + +- Changed the [default log level for `sensu-agent`][157] to `info` (instead of `warn`). + +**FIXES:** + +- The password verification logic when running `sensuctl user change-password` is now included in the backend API rather than sensuctl. +- Errors in publishing proxy check requests no longer block scheduling for other entities. +- Using the `--chunk-size` flag when listing namespaces in sensuctl now works properly. +- The agent no longer immediately exits in certain scenarios when components are disabled. +- Fixed a bug that could cause a GraphQL query to fail when querying a namespace that contained event data in excess of 2 GB. + +## 5.20.2 release notes + +**May 26, 2020** — The latest release of Sensu Go, version 5.20.2, is now available for download. + +This patch release adds username to the API request log to help operators with troubleshooting and user activity reporting, as well as validation for subjects in role-based access control (RBAC) role binding and cluster role binding. +Release 5.20.2 also temporarily disables process discovery so we can investigate and resolve its performance impact on the backend (increased CPU and memory usage). + +Read the [upgrade guide][1] to upgrade Sensu to version 5.20.2. + +**NEW FEATURES:** + +- The API request log now includes the username. + +**FIXES:** + +- ([Commercial feature][141]) [Process discovery in the agent][155] is temporarily disabled. +- The system's libc_type attribute is now properly populated for Ubuntu entities. +- Single-letter subscriptions are now allowed. +- Subjects are now validated in RBAC role binding and cluster role binding. +- [Sensuctl command][154] assets can now be retrieved and installed from Bonsai. + +## 5.20.1 release notes + +**May 15, 2020** — The latest release of Sensu Go, version 5.20.1, is now available for download. + +This patch release includes a bug fix that affects the web UI federated homepage gauges when using the PostgreSQL datastore and several fixes for the data displayed in the web UI entity details. + +Read the [upgrade guide][1] to upgrade Sensu to version 5.20.1. + +**FIXES:** + +- ([Commercial feature][141]) Fixes a bug that prevented the federated homepage in the [web UI][153] from retrieving the keepalive and event gauges when PostgreSQL was configured as the event datastore. +- ([Commercial feature][141]) The [memory_percent and cpu_percent processes attributes][143] are now properly displayed in the [web UI][153]. +- In the [web UI][153], the entity details page no longer displays float type (which applies only for MIPS architectures). Also on entity details pages, the system's libc type is now listed and process names are no longer capitalized. + +## 5.20.0 release notes + +**May 12, 2020** — The latest release of Sensu Go, version 5.20.0, is now available for download. + +This release delivers several new features, substantial improvements, and important fixes. One exciting new feature is agent local process discovery to further enrich entities and their events with valuable context. Other additions include a web UI federation view that provides a single pane of glass for all of your Sensu Go clusters and token substitution for assets. And Windows users rejoice! This release includes many Windows agent fixes, as well as agent log rotation capabilities! + +Read the [upgrade guide][1] to upgrade Sensu to version 5.20.0. + +**NEW FEATURES:** + +- ([Commercial feature][141]) Added a [`processes` field ][143] to the system type to store agent local processes for entities and events and a `discover-processes` option to the [agent configuration options][142] to populate the `processes` field in entity.system if enabled. +- ([Commercial feature][141]) Added a new resource, `GlobalConfig`, that you can use to [customize your web UI configuration][148]. +- ([Commercial feature][141]) Added metricsd to collect metrics for the [web UI][153] and the [`metrics-refresh-interval`][224] backend configuration option for setting the interval at which Sensu should refresh metrics. +- ([Commercial feature][141]) Added process and additional system information to the entity details view in the [web UI][153]. +- ([Commercial feature][141]) Added a PostgreSQL metrics suite so metricsd can collect metrics about events stored in PostgreSQL. +- ([Commercial feature][141]) Added [entity class limits][151] to the license. +- Added check hook output to event details page in the [web UI][153]. +- Added the [sensuctl describe-type command][144] to list all resource types. +The `sensuctl describe-type` command deprecates `sensuctl dump --types`. +- Added `annotations` and `labels` as [backend configuration][145] options. +- Added [token substitution for assets][146]. +- Added `event.is_silenced` and `event.check.is_silenced` [field selectors][138]. +- Added `Edition` and `GoVersion` fields to version information. In commercial distributions, the `Edition` version attribute is set to `enterprise` +- Added ability to configure the Resty HTTP timeout. Also, sensuctl now suppresses messages from the Resty library. + +**IMPROVEMENTS:** + +- ([Commercial feature][141]) The web UI homepage is now a federated view. +- You can now [increment the log level][140] by sending SIGUSR1 to the sensu-backend or sensu-agent process. +- [License metadata][149] now includes the [current entity count and license entity limit][150]. +- In the [web UI][153], users will receive a notification when they try to delete an event without appropriate authorization. +- The Windows agent now has [log rotation][139] capabilities. +- Notepad is now the default editor on Windows rather than vi. + +**FIXES:** + +- ([Commercial feature][141]) Database connections no longer leak after queries to the cluster /health API. +- In the [web UI][153], any leading and trailing whitespace is now trimmed from the username when authenticating. +- The [web UI][153] preferences dialog now displays only the first five groups a user belongs to, which makes the sign-out button more accessible. +- In the [web UI][153], the deregistration handler no longer appears as `undefined` on the entity details page. +- You can now [escape quotes to express quoted strings][147] in token substitution templates. +- The Windows agent now accepts and remembers arguments passed to `service run` and `service install`. +- The Windows agent now synchronizes writes to its log file, so the file size will update with every log line written. +- The Windows agent now logs to both console and log file when you use `service run`. + +## 5.19.3 release notes + +**May 4, 2020** — The latest release of Sensu Go, version 5.19.3, is now available for download. +This is a patch release with many improvements and bug fixes, including a fix to close the event store when the backend restarts, a global rate limit for fetching assets, and fixes for goroutine leaks. Sensu Go 5.19.3 also includes several web UI updates, from fixes to prevent crashes to new color-blindness modes. + +Read the [upgrade guide][1] to upgrade Sensu to version 5.19.3. + +**FIXES:** + +- The event store now closes when the backend restarts, which fixes a bug that allowed Postgres connections to linger after the backend restarted interally. +- The etcd event store now returns exact matches when retrieving events by entity (rather than prefixed matches). +- `sensu-backend init` now logs any TLS failures encountered during initialization. +- `sensuctl logout` now resets the TLS configuration. +- `env_vars` values can now include the equal sign. +- Error logs now include underlying errors encountered when fetching an asset. +- The log level is now WARNING when an asset is not installed because none of the filters match. +- Fixes a bug in the [web UI][135] that could cause labels with links to result in a crash. +- Fixes a bug in the [web UI][135] that could cause the web UI to crash when using an unregistered theme. +- Fixes a bug that could cause the backend to crash. +- Fixes a bug in multi-line metric extraction that appeared in Windows agents. +- Fixes an authentication bug that restarted the sensu-backend when agents disconnected. +- Fixes a bug that meant check `state` and `last_ok` were not computed until the second instance of the event. +- Fixes a bug that caused messages like "unary invoker failed" to appear in the logs. +- Fixes several goroutine leaks. +- Fixes a bug that caused the backend to crash when the etcd client received the error "etcdserver: too many requests." + +**IMPROVEMENTS:** + +- In the [web UI][135], color-blindness modes are now available. +- In the [web UI][135], labels and annotations with links to images will now be displayed inline. +- Adds a global rate limit for fetching assets to prevent abusive asset retries, which you can configure with the `assets-burst-limit` and `assets-rate-limit` configuration options for the [agent][136] and [backend][137]. +- Adds support for restarting the backend via SIGHUP. +- Adds a timeout flag to `sensu-backend init`. +- Deprecated flags for `sensuctl silenced update` subcommand have been removed. + +## 5.19.2 release notes + +**April 27, 2020** — The latest release of Sensu Go, version 5.19.2, is now available for download. +This patch release adds two database connection pool parameters for PostgreSQL so you can configure the maximum time a connection can persist before being destroyed and the maximum number of idle connections to retain. +The release also includes packages for Ubuntu 19.10 and 20.04. + +Read the [upgrade guide][1] to upgrade Sensu to version 5.19.2. + +**FIXES:** + +- ([Commercial feature][122]) Adds SQL database connection pool parameters `max_conn_lifetime` and `max_idle_conns` to store/v1.PostgresConfig132. + +**IMPROVEMENTS:** + +- Sensu packages are now available for Ubuntu 19.10 (Eoan Ermine) and 20.04 (Focal Fossa). Review the [supported platforms][133] page for a complete list of Sensu's supported platforms and the [installation guide][134] to install Sensu packages for Ubuntu. + +## 5.19.1 release notes + +**April 13, 2020** — The latest release of Sensu Go, version 5.19.1, is now available for download. +This is a patch release with a number of bug fixes, including several that affect keepalive events, as well as an addition to the help response for `sensu-backend start` and `sensu-agent start`: the default path for the configuration file. + +Read the [upgrade guide][1] to upgrade Sensu to version 5.19.1. + +**FIXES:** + +- ([Commercial feature][122]) Fixed a bug that caused the PostgreSQL store to be enabled too late upon startup, which caused keepalive bugs and possibly other undiscovered bugs. +- Keepalives now fire correctly when using the PostgreSQL event store. +- Keepalives can now be published via the HTTP API. +- `sensu-agent` no longer allows configuring keepalive timeouts that are shorter than the keepalive interval. +- Eventd no longer mistakes keepalive events for checks with TTL. +- Keepalives now generate a new event universally unique identifier (UUID) for each keepalive failure event. +- Agents now correctly reset keepalive switches on reconnect, which fixes a bug that allowed older keepalive timeout settings to persist. +- Token substitution templates can now express escape-quoted strings. +- The REST API now uses a default timeout of 3 seconds when querying etcd health. +- Pipe handlers now must include a [command][131]. +- The response for `sensu-backend start --help` and `sensu-agent start --help` now includes the configuration file default path. +- The system's `libc_type` attribute is now populated on Alpine containers. + +## 5.19.0 release notes + +**March 30, 2020** — The latest release of Sensu Go, version 5.19.0, is now available for download. +This release is packed with new features, improvements, and fixes, including our first alpha feature: declarative configuration pruning to help keep your Sensu instance in sync with Infrastructure as Code workflows. +Other exciting additions include the ability to save and share your filtered searches in the web UI, plus a new `matches` substring match operator that you can use to refine your filtering results! +Improvements include a new `created_by` field in resource metadata and a `float_type` field that stores whether your system uses hard float or soft float. +We've also added agent and sensuctl builds for MIPS architectures, moved Bonsai logs to the `debug` level, and added PostgreSQL health information to the /health API payload. + +Read the [upgrade guide][1] to upgrade Sensu to version 5.19.0. + +**NEW FEATURES:** + +- ([Commercial feature][122]) In the [web UI][124], you can now [save, recall, and delete filtered searches][123]. +- ([Commercial feature][122]) Added the `matches` substring matching operator for [API response][126], [sensuctl][127], and [web UI][128] filtering selectors. +- ([Commercial feature][122]) Added agent and sensuctl builds for Linux architectures: `mips`, `mipsle`, `mips64`, and `mips64le` (hard float and soft float). +- ([Commercial feature][122]) Sensu now automatically applies the `sensu.io/managed_by` label to resources created via `sensuctl create` for use in the [`sensuctl prune` alpha feature][129]. + +**IMPROVEMENTS:** + +- ([Commercial feature][122]) The [health endpoint][125] now includes PostgreSQL health information. +- Resource metadata now includes the `created_by` field, which Sensu automatically populates with the name of the user who created or last updated each resource. +- The agent now discovers entity libc type, VM system, VM role, and cloud provider. +- System type now includes the `float_type` field, which stores the float type the system is using (hard float or soft float). +- The Bonsai client now logs at the `debug` level rather than the `info` level. +- The store can now create wrapped resources. +- [Tessen][130] now collects the type of store used for events (`etcd` or `postgres`) and logs numbers of authentication providers, secrets, and secrets providers. Tessen data helps us understand how we can improve Sensu, and all Tessen transmissions are logged locally for complete transparency. + +**FIXES:** + +- Fixed a bug where `event.Check.State` was not set for events passing through the pipeline or written to the event log. +- Fixed a bug that allowed the agent to connect to a backend using a nonexistent namespace. +- Fixed a bug that allowed `subscriptions` to be empty strings. +- Corrected the HTTP status codes for unauthenticated and permission denied errors in the REST API. +- Fixed a bug where check history was incorrectly formed when using the PostgreSQL event store. + +## 5.18.1 release notes + +**March 10, 2020** — The latest release of Sensu Go, version 5.18.1, is now available for download. +This release fixes bugs that caused SQL migration failure on PostgreSQL 12, nil pointer panic due to OICD login, and sensu-backend restart upon agent disconnection. +It also includes a reliability improvement — a change to use the gRPC client rather than the embedded etcd client. + +Read the [upgrade guide][1] to upgrade Sensu to version 5.18.1. + +**FIXES:** + +- ([Commercial feature][115]) Fixed a bug that caused SQL migrations to fail on PostgreSQL 12. +- ([Commercial feature][115]) Fixed a bug where OIDC login could result in a nil pointer panic. +- Changed to using the gRPC client (rather than the embedded etcd client) to improve reliability and avoid nil pointer panics triggered by shutting down the embedded etcd client. +- The Sensu backend no longer hangs indefinitely if a file lock for the asset manager cannot be obtained. Instead, the backend returns an error after 60 seconds. +- Fixed a bug that caused sensu-backend to restart when agents disconnected. +- Fixed a bug where the backend would panic on some 32-bit systems. + +## 5.18.0 release notes + +**February 25, 2020** — The latest release of Sensu Go, version 5.18.0, is now available for download. +This release delivers a number of improvements to the overall Sensu Go experience. +From automatic proxy entity creation to unique Sensu event IDs, it's now much easier to use and troubleshoot your monitoring event pipelines! +If you're working behind an HTTP proxy, you can now manage remote Sensu Go clusters, as sensuctl now honors proxy environment variables (for example, HTTPS_PROXY). +This release also includes a number of fixes for usability bugs, making for the most polished release of Sensu Go yet, so go ahead and give it a download! + +Read the [upgrade guide][1] to upgrade Sensu to version 5.18.0. + +**IMPROVEMENTS:** + +- The `event.entity.entity_class` value now defaults to `proxy` for [`POST /events`][114] requests. +- If you use the [core/v2/events API][118] to create a new event with an entity that does not already exist, the sensu-backend will automatically create a proxy entity when the event is published. +- Sensuctl now accepts Bonsai asset versions that include a prefix with the letter `v` (for example, `v1.2.0`). +- The /version API now retrieves the Sensu agent version for the Sensu instance. +- Log messages now indicate which filter dropped an event. +- Sensu now reads and writes `initializationKey` to and from EtcdRoot, with legacy support (read-only) as a fallback. +- Sensu will now check for an HTTP response other than `200 OK` response when fetching assets. +- Updated Go version from 1.13.5 to 1.13.7. + +**FIXES:** + +- ([Commercial feature][115]) [Label selectors][116] and [field selectors][117] now accept single and double quotes to identify strings. +- Fixed a bug that prevented wrapped resources from having their namespaces set by the default sensuctl configuration. +- Fixed a bug that prevented [API response filtering][119] from working properly for core/v2/silenced API endpoints. +- Improved event payload validation for the [core/v2/events API][118] so that events that do not match the URL parameters on the `/events/:entity/:check` endpoint are rejected. +- Sensuctl now supports the `http_proxy`, `https_proxy`, and `no_proxy` environment variables. +- The [`auth/test` endpoint][120] now returns the correct error messages. + +## 5.17.2 release notes + +**February 19, 2020** — The latest release of Sensu Go, version 5.17.2, is now available for download. +This release fixes a bug that could prevent commercial features from working after internal restart. + +Read the [upgrade guide][1] to upgrade Sensu to version 5.17.2. + +**FIXES:** + +- Fixed a bug that could cause commercial HTTP routes to fail to initialize after an internal restart, preventing commercial features from working. + +## 5.17.1 release notes + +**January 31, 2020** — The latest release of Sensu Go, version 5.17.1, is now available for download. +This release fixes a web UI issue that cleared selected filters when sorting an event list and a bug that prevented certain `.tar` assets from extracting. +It also includes sensuctl configuration improvements. + +Read the [upgrade guide][1] to upgrade Sensu to version 5.17.1. + +**IMPROVEMENTS:** + +- Asset names may now include capital letters. +- Running the `sensuctl configure` command now resets the sensuctl cluster configuration. +- When you use `--trusted-ca-file` to configure sensuctl, it now detects and saves the absolute file path in the cluster configuration. + +**FIXES:** + +- ([Commercial feature][106]) When a silencing entry expires or is removed, it is also removed from the silences view in the [web UI][107]. +- Fixed a bug that prevented `.tar` assets from extracting if they contain hardlinked files. +- In the [web UI][107], sorting an event list view no longer clears the selected filters. + +## 5.17.0 release notes + +**January 28, 2020** — The latest release of Sensu Go, version 5.17.0, is now available for download. +This is a significant release, with new features, improvements, and fixes! +We're ecstatic to announce the release of secrets management, which eliminates the need to expose sensitive information in your Sensu configuration. +When a Sensu component such as a check or handler requires a secret (like a username or password), Sensu will be able to fetch that information from one or more external secrets providers (for example, HashiCorp Vault) and provide it to the Sensu component via temporary environment variables. +Secrets management allows you to move secrets out of your Sensu configuration, giving you the ability to safely and confidently share your Sensu configurations with your fellow Sensu users! +This release also includes per-entity keepalive event handler configuration, a sought-after feature for users who have migrated from Sensu 1.x to Sensu Go. + +Read the [upgrade guide][1] to upgrade Sensu to version 5.17.0. + +**NEW FEATURES:** + +- ([Commercial feature][106]) Added [HTTP API for secrets management][108], with Sensu's `Env` secrets provider and support for HashiCorp Vault secrets management. The secrets provider resource is implemented for checks, mutators, and handlers. +- Added the `keepalive-handlers` agent configuration option to specify the keepalive handlers to use for an entity's events. + +**IMPROVEMENTS:** + +- ([Commercial feature][106]) Upgraded the size of the events auto-incremented ID in the PostgreSQL store to a 64-bit variant, which allows you to store many more events and avoids exhausting the sequence. +- ([Commercial feature][106]) [Initialization][109] via `sensu-backend init` is now implemented for Docker. +- ([Commercial feature][106]) UPN binding support has been re-introduced via the `default_upn_domain` configuration attribute. +- In the [web UI][107], labels that contain URLs are now clickable links. +- Added `event.entity.name` as a supported field for the [`fieldSelector`][110] query parameter. +- In the [web UI][107], users with implicit permissions to a namespace can now display resources within that namespace. +- Explicit access to namespaces can only be granted via [cluster-wide RBAC resources][111]. +- You can now omit the namespace from an event in [`HTTP POST /events`][112] requests. +- Added support for the `--format` flag in the [sensuctl command list][113] subcommand. + +**FIXES:** + +- ([Commercial feature][106]) Fixed a bug where the event check state was not present when using the PostgreSQL event store. +- ([Commercial feature][106]) Agent TLS authentication does not require a license. +- Fixed a memory leak in the entity cache. +- Fixed a bug that prevented `sensuctl entity delete` from returning an error when attempting to delete a non-existent entity. +- In the [web UI][107], fixed a bug that duplicated event history in the event timeline chart. +- `sensuctl command` assets installed via Bonsai now use the `sensuctl` namespace. +- Fixed a bug where failing check TTL events could occur if keepalive failures had already occurred. + +## 5.16.1 release notes + +**December 18, 2019** — The latest release of Sensu Go, version 5.16.1, is now available for download. +This release fixes a performance regression that caused API latency to scale linearly as the number of connected agents increased and includes a change to display the `sensu_go_events_processed` Prometheus counter by default. + +Read the [upgrade guide][1] to upgrade Sensu to version 5.16.1. + +**IMPROVEMENTS** + +- The `sensu_go_events_processed` Prometheus counter now initializes with the `success` label so the count is always displayed. + +**FIXES:** + +- The performance regression introduced in 5.15.0 that caused API latency to scale linearly as the number of connected agents increased is fixed. + +## 5.16.0 release notes + +**December 16, 2019** — The latest release of Sensu Go, version 5.16.0, is now available for download. +This is another important release, with many new features, improvements, and fixes. +We introduced an initialization subcommand for **new** installations that allows you to specify an admin username and password instead of using a pre-defined default. +We also added new backend configuration options to help you take advantage of etcd auto-discovery features and agent configuration options you can use to define a timeout period for critical and warning keepalive events. + +New web UI features include a switcher that makes it easier to switch between namespaces in the dashboard, breadcrumbs on every page, OIDC authentication in the dashboard, a drawer that replaces the app bar to make more room for content, and more. + +We also fixed issues with `sensuctl dump` and `sensuctl cluster health`, installing sensuctl commands via Bonsai, and missing namespaces in keepalive events and events created through the agent socket interface. + +Read the [upgrade guide][1] to upgrade Sensu to version 5.16.0. + +**IMPORTANT:** + +- For Debian- and RHEL-family installations, the backend is no longer seeded with a default admin username and password. +Users will need to [run 'sensu-backend init'][102] on every new installation and specify an admin username and password. + +**NEW FEATURES:** + +- ([Commercial feature][105]) Users can now authenticate with OIDC in the dashboard. +- ([Commercial feature][105]) Label selectors now match the event's check and entity labels. +- Added a new configuration option, `etcd-client-urls`, to use with sensu-backend when it is not operating as an etcd member. +The configuration option is also used by the new `sensu-backend init` subcommand. +- Added the ['sensu-backend init' subcommand][102]. +- Added the [`etcd-discovery`][100] and [`etcd-discovery-srv`][292] configuration options to sensu-backend, which allow users to take advantage of the embedded etcd's auto-discovery features. +- Added the [`keepalive-critical-timeout`][101] configuration option to define the time after which a critical keepalive event should be created for an agent and the [`keepalive-warning-timeout`][101] configuration option, which is an alias of `keepalive-timeout` for backward compatibility. + +**IMPROVEMENTS:** + +- ([Commercial feature][105]) The entity limit warning message is now displayed less aggressively and the warning threshold is proportional to the entity limit. +- A new switcher in the [web UI][103] makes it easier to switch namespaces in the dashboard. +Access the new component from the drawer or with the shortcut ctrl+k. +For users who have many namespaces, the switcher now includes fuzzy search and improved keyboard navigation. +- In the [web UI][103], replaced the app bar with an omnipresent drawer to increase the available space for content. Each page also now includes breadcrumbs. +- In the [Sensu documentation][104], links now point to the version of the product being run instead of the latest, which may be helpful when running an older version of Sensu. + +**FIXES:** + +- `sensuctl dump` help now shows the correct default value for the format flag. +- Installing sensuctl commands via Bonsai will now check for correct labels before checking if the asset has 1 or more builds. +- Listing assets with no results now returns an empty array. +- Fixed a panic that could occur when creating resources in a namespace that does not exist. +- Fixed an issue where keepalive events and events created through the agent's socket interface could be missing a namespace. +- Fixed an issue that could cause 'sensuctl cluster health' to hang indefinitely. +- ([Commercial feature][105]) The `agent.yml.example` file shipped with Sensu Agent for Windows packages now uses DOS-style line endings. + +## 5.15.0 release notes + +**November 19, 2019** — The latest release of Sensu Go, version 5.15.0, is now available for download. +This is a significant release for a number of reasons. +The changes to licensing make 100% of Sensu Go's commercial features available for free to all users, up to your first 100 entities! +This release also includes the long-awaited cluster federation features, supporting multi-cluster authentication, RBAC policy replication, and a single pane of glass for your Sensu monitoring data! +We added support for API keys, making it easy to integrate with the Sensu API (you no longer need to manage JWTs). +In addition, the 5.15.0 release includes support for sensu-backend environment variables and bug fixes that improve error logging for mutator execution and flap detection weighting for checks. + +Read the [upgrade guide][1] to upgrade Sensu to version 5.15.0. + +**IMPORTANT:** +Sensu's free entity limit is now 100 entities. +All [commercial features][95] are available for free in the packaged Sensu Go distribution for up to 100 entities. +You will receive a warning when you approach the 100-entity limit (at 75%). + +If your Sensu instance includes more than 100 entities, [contact us][90] to learn how to upgrade your installation and increase your limit. +Read the [blog announcement][91] for more information about our usage policy. + +**NEW FEATURES:** + +- ([Commercial feature][95]) Added support for [federation replicators and the federation cluster registration API][85] and the ability to view resources across clusters in the federation in the [web UI][80]. +- ([Commercial feature][95]) Added MSI and NuGet builds for [sensuctl][89]. Also, MSI and NuGet installations now add the bin directory to the system PATH on Windows. +- ([Commercial feature][95]) Added HTTP DELETE access for the [license management API][92]. +- Added the [APIKey resource][86], with HTTP API support for POST, GET, and DELETE and [sensuctl commands][87] to manage the APIKey resource. +- Added support for using [API keys for API authentication][88]. +- Added support for [sensuctl commands][93] to install, execute, list, and delete commands from Bonsai or a URL. +- Added support for sensu-backend service environment variables. +- Added support for [timezones in check `cron` strings][94]. + +**SECURITY:** + +- ([Commercial feature][95]) Removed support for UPN binding without a binding account or anonymous binding, which allows Sensu to effectively refresh claims during access token renewal. + +**IMPROVEMENTS:** + +- You can now use colons and periods in all resource names (except users). + +**FIXES:** + +- Added better error logging for mutator execution. +- Fixed the order of flap detection weighting for checks. +- Fixed the pprof server so it only binds to localhost. +- Moved `corev2.BonsaiAsset` to `bonsai.Asset` and moved `corev2.OutdatedBonsaiAsset` to `bonsai.OutdatedAsset`. + +## 5.14.2 release notes + +**November 4, 2019** — The latest release of Sensu Go, version 5.14.2, is now available for download. +This release includes an etcd upgrade, fixes that improve stability and performance, and a Sensu Go package for RHEL 8. + +Read the [upgrade guide][1] to upgrade Sensu to version 5.14.2. + +**IMPROVEMENTS:** + +- Upgraded etcd to 3.3.17. +- Added build package for RHEL 8 (`el/8`). +- Sensu Go now uses serializable event reads, which helps improve performance. + +**FIXES:** + +- As a result of upgrading etcd, TLS etcd clients that lose their connection will successfully reconnect when using the `no-embed-etcd` configuration option. +- Check TTL and keepalive switches are now correctly buried when associated events and entities are deleted. +As a result, Sensu now uses far fewer leases for check TTLs and keepalives, which improves stability for most deployments. +- Corrected a minor UX issue in interactive filter commands in sensuctl. + +## 5.14.1 release notes + +**October 16, 2019** — The latest release of Sensu Go, version 5.14.1, is now available for download. +This release adds Prometheus gauges for check schedulers and fixes several bugs, including a bug discovered in 5.14.0 that prevented OIDC authentication providers from properly loading on start-up. + +Read the [upgrade guide][1] to upgrade Sensu to version 5.14.1. + +**NEW FEATURES:** + +- Added Prometheus gauges for check schedulers. + +**FIXES:** + +- ([Commercial feature][79]) Sensuctl will not incorrectly warn of entity limits for unlimited licenses. +- ([Commercial feature][79]) `oidc` authentication providers will now properly load on start-up. +- When opening a Bolt database that is already open, `sensu-agent` will not hang indefinitely. +- Running [`sensuctl dump`][84] for multiple resource types with the output format as YAML will not result in separators being printed to stdout instead of the specified file. +- Fixed a crash in sensu-backend (panic: send on closed channel). + +## 5.14.0 release notes + +**October 8, 2019** — The latest release of Sensu Go, version 5.14.0, is now available for download. +This release includes feature additions like two new configuration options for backends using embedded etcd and a new SemVer field in entity resources. +In addition, this release includes enhanced TLS authentication support and bug fixes that restore check execution after a network error and enable round robin schedule recovery after quorum loss. + +Read the [upgrade guide][1] to upgrade Sensu to version 5.14.0. + +**NEW FEATURES:** + +- The [web UI][80] now includes an error dialog option that allows users to wipe the application's persisted state (rather than having to manually wipe their local/session storage). +This can help in the rare case that something in the persisted state is leading to an uncaught exception. +- The [web UI][80] now respects the system preference for operating systems with support for selecting a preferred light or dark theme. +- `sensuctl dump` can now list the types of supported resources with `sensuctl dump --types`. +- The [entity resource][82] now includes the `sensu_agent_version` field, which reflects the Sensu Semantic Versioning (SemVer) version of the agent entity. +- There are two new [advanced configuration options][83] for `sensu-backend` using embedded etcd: `etcd-heartbeat-interval` and `etcd-election-timeout`. + +**IMPROVEMENTS:** + +- ([Commercial feature][79]) Added support for mutual TLS authentication between agents and backends. +- ([Commercial feature][79]) Added support for CRL URLs for mTLS authentication. +- ([Commercial feature][79]) Support agent [TLS authentication][81] is usable with the sensu-backend. +- In the web UI, feedback is directed to Discourse rather than the GitHub repository's Issues page to facilitate discussion about feature requests. +- In the [web UI][80], when a user lands on a page inside a namespace that no longer exists or they do not have access to, the drawer opens to that namespace switcher to help clarify next steps. +- Updated Go version from 1.12.3 to 1.13.1. + +**FIXES:** + +- ([Commercial feature][79]) `sensuctl` on Windows can now create Postgres resources. +- ([Commercial feature][79]) Fixed a bug that resulted in event metrics being ignored when using the Postgres store. +- Fixed a bug that caused checks to stop executing after a network error. +- Fixed a bug that prevented `sensuctl create` with stdin from working. +- Splayed proxy checks are executed every interval (instead of every interval + interval * splay_coverage). +- Proxy entity labels and annotations are now redacted in the web UI as expected. +- Fixed a bug in the ring that prevented round robin schedules from recovering after quorum loss. +- Updated [web UI][80] so that unauthorized errors emitted while creating silences or resolving events are caught and a notification is presented to communicate what occurred. +- [Web UI][80] does not report internal errors when a user attempts to queue an ad hoc check for a keepalive. +- Fixed a bug in the [web UI][80] that may have prevented users with appropriate roles from resolving events, queuing checks, and creating silenced entries. +- Asset builds are not separated into several assets unless the the tabular format is used in `sensuctl asset list`. +- The 'flag accessed but not defined' error is corrected in `sensuctl asset outdated`. + +## 5.13.2 release notes + +**September 19, 2019** — The latest release of Sensu Go, version 5.13.2, is now available for download. +This is a stability release that fixes a bug for users who have the PostgreSQL event store enabled. + +Read the [upgrade guide][1] to upgrade Sensu to version 5.13.2. + +**FIXES:** + +- Metrics handlers now correctly receive metric points when the postgresql event store is enabled. + +## 5.13.1 release notes + +**September 10, 2019** — The latest release of Sensu Go, version 5.13.1, is now available for download. +This is a stability release with bug fixes for multi-build asset definitions causing a panic when no matching filters are found. + +Read the [upgrade guide][1] to upgrade Sensu to version 5.13.1. + +**FIXES:** + +- Multi-build asset definitions with no matching filters will no longer cause a panic. +- Fixed the `oidc` authentication provider resource. + +## 5.13.0 release notes + +**September 9, 2019** — The latest release of Sensu Go, version 5.13.0, is now available for download. +This is one of the most user-friendly releases yet! +Sensuctl now integrates with Bonsai, the Sensu asset hub, making it easier than ever to fetch and use countless Sensu monitoring plugins and integrations. +Additionally, sensuctl now supports loading resource configuration files (for example, checks) from directories and URLs. +But that's not all! +Sensuctl now provides a subcommand for exporting its configuration and API tokens to your shell environment. +Use sensuctl to provide cURL and custom scripts with fresh API access information! + +Read the [upgrade guide][1] to upgrade Sensu to version 5.13.0. + +**NEW FEATURES:** + +- Sensuctl now integrates with Bonsai, the Sensu asset hub. +Run a single sensuctl command to add an asset to your Sensu cluster (for example, `sensuctl asset add sensu/sensu-pagerduty-handler:1.1.0`). +Check for outdated assets (new releases available) with the `outdated` subcommand (for example, `sensuctl asset outdated`). +- Sensuctl now supports the `env` subcommand for exporting sensuctl configuration and API tokens to your shell environment (for example, `eval $(sensuctl env)`). +- Sensuctl now supports loading multiple resource configuration files (for example, checks and handlers) from directories! +Sensuctl can also load a file using a URL (for example, `sensuctl create -r -f ./checks` and `sensuctl create -f https://my.blog.ca/sensu-go/check.yaml`). + +**FIXES:** + +- Sensuctl interactive check create and update modes now have `none` for the metric output format as the first highlighted option instead of `nagios-perfdata`. +- Fixed a bug where silences would not expire on event resolution. + +## 5.12.0 release notes + +**August 26, 2019** — The latest release of Sensu Go, version 5.12.0, is now available for download. +There are some exciting feature additions in this release, including the ability to output resources to a file from sensuctl and more granular control of check and check hook execution with an agent allow list. +Additionally, this release includes the ability to delete assets and more stability fixes around watcher functionality. + +Read the [upgrade guide][1] to upgrade Sensu to version 5.12.0. + +**IMPORTANT:** + +Due to changes in the release process, Sensu binary-only archives are now named following the pattern `sensu-go_5.12.0_$OS_$ARCH.tar.gz`, where `$OS` is the operating system name and `$ARCH` is the CPU architecture. +These archives include all files in the top level directory. +Read the [installation guide][16] for the latest download links. + +**NEW FEATURES:** + +- Operators can now authenticate to Sensu via OpenID Direct Connect (OIDC) using sensuctl. +Read the [authentication documentation][17] for details. +- Added sensu-agent and sensuctl binary builds for FreeBSD. +- Added sensuctl dump command to output resources to a file or stdout, making it easier to back up your Sensu backends. +- Agents can now be configured with a list of executables that are allowed to run as check and hook commands. +Read the [agent reference][78] for more information. + +**IMPROVEMENTS:** + +- Assets now support defining multiple builds, reducing the number of individual assets needed to cover disparate platforms in your infrastructure. +- ([Commercial feature][53]) Namespaces listed in both the web UI and sensuctl are now limited to the namespace to which the user has access. +- Hooks now support the use of assets. +- The event.check.name field has been added as a supported field selector. +- Both the API and sensuctl can now be used to delete assets. +- The use of ProtoBuf serialization/deserialization over WebSocket can now be negotiated between agent and backend. +- Web UI performance has been improved for deployments with many events and entities. +- The resource caches can now rebuild themselves in case of failures. +- Event and entity resources can now be created via the API without an explicit namespace. +The system will refer to the namespace in the request URL. +- Event and entity resources can now be created via the API using the POST verb. + +**SECURITY:** + +- To prevent writing sensitive data to logs, the backend no longer logs decoded check result and keepalive payloads. + +**FIXES:** + +- Tabular display of filters via sensuctl now displays `&&` or `||` as appropriate for inclusive and exclusive filters, respectively. +- Requesting events from the `GET /events/:entity` API endpoint now returns events only for the specified entity. +- Running sensuctl config view without configuration no longer causes a crash. +- Creating an entity via sensuctl with the `--interactive` flag now prompts for the entity name when it is not provided on the command line. +- Check hooks with `stdin: true` now receive actual event data on stdin instead of an empty event. +- Some issues with check scheduling and updating have been fixed by refactoring the backend's watcher implementation. + +**KNOWN ISSUES:** + +- Authentication via OIDC is not yet supported in the web UI. +- Deleting an asset will not remove references to said asset. +It is the operator's responsibility to remove the asset from the runtime_assets field of the check, hook, filter, mutator, or handler. +- Deleting an asset will not remove the tarball or downloaded files from disk. +It is the operator's responsibility to clear the asset cache if necessary. + +## 5.11.1 release notes + +**July 18, 2019** — The latest release of Sensu Go, version 5.11.1, is now available for download. +This is a stability release with bug fixes for UPN format binding token renewal and addition of agent heartbeats and configurable WebSocket connection negotiation. + +Read the [upgrade guide][1] to upgrade Sensu to version 5.11.1. + +**FIXES:** + +- Fixed access token renewal when UPN format binding was enabled. +- The agent now sends heartbeats to the backend to detect network failures and reconnect more quickly. +- The default handshake timeout for the WebSocket connection negotiation was lowered from 45 to 15 seconds and is now configurable. + +## 5.11.0 release notes + +**July 10, 2019** — The latest release of Sensu Go, version 5.11.0, is now available for download. +There are some exciting feature additions in this release, including the ability to delete resources from sensuctl and manage filter and mutator resources in the web UI. +Additionally, this release includes bug fixes for proxy checks and enhanced performance tuning for the PostgreSQL event store. + +Read the [upgrade guide][1] to upgrade Sensu to version 5.11.0. + +**NEW FEATURES:** + +- The Sensu [web UI][67] now includes a filters page that displays available event filters and filter configuration. +- ([Commercial feature][68]) Manage your Sensu event filters from your browser: Sensu's [web UI][67] now supports creating, editing, and deleting filters. +- The Sensu [web UI][67] now includes a mutators page that displays available mutators and mutator configuration. +- ([Commercial feature][68]) Manage your Sensu mutators from your browser: Sensu's [web UI][67] now supports creating, editing, and deleting mutators. +- Sensuctl now includes the `sensuctl delete` command, letting you use resource definitions to delete resources from Sensu in the same way as `sensuctl create`. +Read the [sensuctl reference][72] for more information. +- Assets now include a `headers` attribute to include HTTP headers in requests to retrieve assets, allowing you to access secured assets. +Read the [asset reference][70] for examples. +- Sensu agents now support the `disable-assets` configuration option, allowing you to disable asset retrieval for individual agents. +Read the [agent reference][71] for examples. +- Sensu [binary-only distributions][69] are now available as zip files. + +**IMPROVEMENTS:** + +- ([Commercial feature][68]) The [Active Directory authentication provider][74] now supports the `default_upn_domain` attribute, letting you appended a domain to a username when a domain is not specified during login. +- ([Commercial feature][68]) The [Active Directory authentication provider][74] now supports the `include_nested_groups` attribute, letting you search nested groups instead of just the top-level groups of which a user is a member. +- The `sensuctl config view` command now returns the currently configured username. +Read the [sensuctl reference][76] for examples. +- The [Sensu API][75] now returns the `201 Created` response code for POST and PUT requests instead of `204 No Content`. +- The Sensu backend now provides [advanced configuration options][77] for buffer size and worker count of keepalives, events, and pipelines. +- Sensu Go now supports Debian 10. +For a complete list of supported platforms, visit the [platforms page][73]. + +**FIXES:** + +- The web UI now returns an error when attempting to create a duplicate check or handler. +- Silenced entries are now retrieved from the cache when determining whether an event is silenced. +- The Sensu API now returns an error when trying to delete an entity that does not exist. +- The agent WebSocket connection now performs basic authorization. +- The core/v2/events API now correctly applies the current timestamp by default, fixing a regression in 5.10.0. +- Multiple nested set handlers are now flagged correctly, fixing an issue in which they were flagged as deeply nested. +- Round robin proxy checks now execute as expected in the event of updated entities. +- The Sensu backend now avoids situations of high CPU usage in the event that watchers enter a tight loop. +- Due to incompatibility with the Go programming language, Sensu is incompatible with RHEL 5. +As a result, RHEL 5 has been removed as a [supported platform][73] for all versions of Sensu Go. + +## 5.10.2 release notes + +**June 27, 2019** — The latest release of Sensu Go, version 5.10.2, is now available for download. +This is a stability release with a bug fix for expired licenses. + +Read the [upgrade guide][1] to upgrade Sensu to version 5.10.2. + +**FIXES:** + +- Sensu now handles expired licenses as expected. + +## 5.10.1 release notes + +**June 25, 2019** — The latest release of Sensu Go, version 5.10.1, is now available for download. +This is a stability release with key bug fixes for proxy checks and entity deletion. + +Read the [upgrade guide][1] to upgrade Sensu to version 5.10.1. + +**FIXES:** + +- The proxy_requests entity_attributes are now all considered when matching entities. +- Events are now removed when their corresponding entity is deleted. + +## 5.10.0 release notes + +**June 19, 2019** — The latest release of Sensu Go, version 5.10.0, is now available for download. +There are some exciting feature additions in this release, including the ability to perform advanced filtering in the web UI and use PostgreSQL as a scalable event store. +This release also includes key bug fixes, most notably for high CPU usage. + +Read the [upgrade guide][1] to upgrade Sensu to version 5.10.0. + +**NEW FEATURES:** + +- ([Commercial feature][60]) The Sensu web UI now includes fast, predictive filtering for viewing checks, entities, events, handlers, and silences, including the ability to filter based on custom labels. +Select the filter bar and start building custom views using suggested attributes and values. +For more information, read the [web UI docs][66]. +- Free Sensu instances can now delete entities in the web UI entities page. +Read the [web UI docs][65] to get started using the Sensu web UI. +- ([Commercial feature][60]) Sensu now supports using an external PostgreSQL instance for event storage in place of etcd. +PostgreSQL can handle significantly higher volumes of Sensu events, letting you scale Sensu beyond etcd's storage limits. +Read the [datastore reference][61] for more information. +- Sensu now includes a cluster ID API endpoint and `sensuctl cluster id` command to return the unique Sensu cluster ID. +Read the [core/v2/cluster API endpoint docs][62] for more information. + +**IMPROVEMENTS:** + +- The `sensuctl create` command now supports specifying the namespace for a group of resources at the time of creation, allowing you to replicate resources across namespaces without manual editing. +Read the [sensuctl reference][63] for more information and usage examples. +- Sensu cluster roles can now include permissions to manage your Sensu license using the `license` resource type. +Read the [RBAC reference][64] to create a cluster role. +- The web UI now displays up to 100,000 events and entities on the homepage. + +**FIXES:** + +- Sensu now optimizes scheduling for proxy checks, solving an issue with high CPU usage when evaluating proxy entity attributes. +- The Sensu API now validates resource namespaces and types in request bodies to ensure RBAC permissions are enforced. +- Check `state` and `total_state_change` attributes now update as expected based on check history. +- Incident and entity links in the web UI homepage now navigate to the correct views. +- The web UI now displays non-standard cron statements correctly (for example, `@weekly`). +- On sign-in, the web UI now ensures that users are directed to a valid namespace. +- In the web UI, code block scrollbars now display only when necessary. +- The web UI now displays the handler `timeout` attribute correctly. +- When editing resources, the web UI now fetches the latest resource prior to editing. +- The web UI now handles array values correctly when creating and editing resources. + +## 5.9.0 release notes + +**May 28, 2019** — The latest release of Sensu Go, version 5.9.0, is now available for download. +There are some exciting feature additions in this release, including the ability to log raw events to a file (commercial feature) and view event handlers in the web UI. + +Read the [upgrade guide][52] to upgrade Sensu to version 5.9.0. +If you're upgrading a Sensu cluster from 5.7.0 or earlier, read the [instructions for upgrading a Sensu cluster from 5.7.0 or earlier to 5.8.0 or later][59]. + +**NEW FEATURES:** + +- The Sensu web UI now includes a handlers page that displays available event handlers and handler configuration. +Read the [web UI docs][54] to get started using the Sensu web UI. +- ([Commercial feature][53]) Manage your Sensu event handlers from your browser: Sensu's web UI now supports creating, editing, and deleting handlers. +Read the [web UI docs][54] to get started using the Sensu web UI. +- ([Commercial feature][53]) Sensu now supports event logging to a file using the `event-log-file` and `event-log-buffer-size` configuration options. +You can use this event log file as an input source for your favorite data lake solution. +Read the [backend reference][55] for more information. + +**IMPROVEMENTS:** + +- The Sensu web UI now includes simpler, more efficient filtering in place of filtering using Sensu query expressions. +- Sensu packages are now available for Ubuntu 19.04 (Disco Dingo). Review the [supported platforms page][56] for a complete list of Sensu's supported platforms and the [installation guide][57] to install Sensu packages for Ubuntu. + +**FIXES:** + +- The `occurrences` and `occurrences_watermark` event attributes now increment as expected, giving you useful information about recent events. +Read the [events reference][58] for an in-depth discussion of these attributes. +- The `/silenced/subscriptions/:subscription` and `/silenced/checks/:check` API endpoints now return silences by check or subscription. +- Sensu now handles errors when seeding initial data, avoiding a panic state. + +## 5.8.0 release notes + +**May 22, 2019** — The latest release of Sensu Go, version 5.8.0, is now available for download. +This is mainly a stability release with bug fixes and performance improvements. +Additionally, we have added support for configurable etcd cipher suites. + +Read the [upgrade guide][51] to upgrade Sensu to version 5.8.0. + +**IMPORTANT:** + +- To upgrade to Sensu Go 5.8.0, Sensu clusters with multiple backend nodes must be shut down during the upgrade process. +Read the [upgrade guide][51] for more information. + +**IMPROVEMENTS:** + +- The sensuctl command line tool now supports the `--chunk-size` flag to help you handle large datasets. +Read the [sensuctl reference][45] for more information. +- Sensu backends now support the `etcd-cipher-suites` configuration option, letting you specify the cipher suites that can be used with etcd TLS configuration. +Read the [backend reference][47] for more information. +- The Sensu API now includes the /version API, returning version information for your Sensu instance. +Review the [API docs][46] for more information. +- Tessen now collects the numbers of events processed and resources created, giving us better insight into how we can improve Sensu. +As always, all Tessen transmissions are logged for complete transparency. +Read the [Tessen reference][48] for more information. +- Sensu licenses now include the entity limit attached to your Sensu licensing package. +Read the [license management docs][49] to learn more about entity limits. +- Sensu backends now perform better at scale using increased worker pool sizes for events and keepalives. +- The maximum size of the etcd database and etcd requests is now configurable using the `etcd-quota-backend-bytes` and `etcd-max-request-bytes` backend configuration options. +These are advanced configuration options requiring familiarly with etcd. +Use with caution. +Read the [backend reference][50] for more information. +- Most Sensu resources now use ProtoBuf serialization in etcd. + +**FIXES:** + +- Events produced by checks now execute the correct number of write operations to etcd. +- API pagination tokens for the core/v2/users and core/v2/namespaces API endpoints now work as expected. +- Keepalive events for deleted and deregistered entities are now cleaned up as expected. + +**KNOWN ISSUES:** + +- Auth tokens may not be purged from etcd, resulting in a possible impact to performance. + +## 5.7.0 release notes + +**May 9, 2019** — The latest release of Sensu Go, version 5.7.0, is now available for download. +This is mainly a stability release with bug fixes. +Additionally, we have added support for Windows packages and [updated our usage policy][44]. + +Read the [upgrade guide][1] to upgrade Sensu to version 5.7.0. + +**IMPROVEMENTS:** + +- The Sensu agent for Windows is now available as an MSI package, making it easier to install and operate. +Read the [installation guide][41] and the [agent reference][42] to get started. + +**FIXES:** + +- Sensu now enforces resource separation between namespaces sharing a similar prefix. +- The `sensuctl cluster` commands now output correctly in JSON and wrapped JSON formats. +- The API now returns an error message if [label and field selectors][43] are used without a license. + +## 5.6.0 release notes + +**April 30, 2019** — The latest release of Sensu Go, version 5.6.0, is now available for download. +We have added some exciting new features in this release, including API filtering and the ability to create and manage checks through the web UI with the presence of a valid license key. + +Read the [upgrade guide][1] to upgrade Sensu to version 5.6.0. + +**NEW FEATURES:** + +- ([Commercial feature][33]) Manage your Sensu checks from your browser: Sensu's web user interface now supports creating, editing, and deleting checks. +Read the [web UI docs][32] to get started using the Sensu web UI. +- ([Commercial feature][33]) The Sensu web UI now includes an option to delete entities. +- ([Commercial feature][33]) Sensu now supports resource filtering in the Sensu API and sensuctl command line tool. +Filter events using custom labels and resource attributes, such as event status and check subscriptions. +Review the [API docs][34] and [sensuctl reference][35] for usage examples. + +**IMPROVEMENTS:** + +- ([Commercial feature][33]) Sensu's LDAP and Active Directory integrations now support mutual authentication using the `trusted_ca_file`, `client_cert_file`, and `client_key_file` attributes. +Read the [guide to configuring an authentication provider][37] for more information. +- ([Commercial feature][33]) Sensu's LDAP and Active Directory integrations now support connecting to an authentication provider using anonymous binding. +Read the [LDAP][38] and [Active Directory][39] binding configuration docs to learn more. +- the [/health API][36] response now includes the cluster ID. +- The `sensuctl cluster health` and `sensuctl cluster member-list` commands now include the cluster ID in tabular format. + +**FIXES:** + +- You can now configure labels and annotations for Sensu agents using command line flags. +For example: `sensu-agent start --label example_key="example value"`. +Read the [agent reference][40] for more examples. +- The Sensu web UI now displays the correct checkbox state when no resources are present. + +## 5.5.1 release notes + +**April 17, 2019** — The latest release of Sensu Go, version 5.5.1, is now available for download. +This is a stability release with key bug fixes, including addressing an issue with backend CPU utilization. +Additionally, we have added support for honoring the source attribute for events received via agent socket. + +Read the [upgrade guide][1] to upgrade Sensu to version 5.5.1. + +**IMPROVEMENTS:** + +- Sensu agents now support annotations (non-identifying metadata) that help people or external tools interacting with Sensu. +Read the [agent reference][29] to add annotations in the agent configuration file. +- The [agent socket event format][30] now supports the `source` attribute to create a proxy entity. +- Sensu 5.5.1 is built with Go version 1.12.3. + +**FIXES:** + +- Backends now reinstate etcd watchers in the event of a watcher failure, fixing an issue causing high CPU usage in some components. + +## 5.5.0 release notes + +**April 4, 2019** — The latest release of Sensu Go, version 5.5.0, is now available for download. +This release has some key bug fixes and additions, including the introduction of Tessen into Sensu Go. +For more information, read Sean Porter's [blog post][28] on Tessen. + +Read the [upgrade guide][1] to upgrade Sensu to version 5.5.0. + +**NEW FEATURES:** + +- Tessen, the Sensu call-home service, is now enabled by default in Sensu backends. +Read the [Tessen docs][27] to learn about the data that Tessen collects. + +**IMPROVEMENTS:** + +- Sensu now includes more verbose check logging to indicate when a proxy request matches an entity according to its entity attributes. + +**FIXES:** + +- The Sensu web UI now displays silences created by LDAP users. +- The web UI now uses a secondary text color for quick-navigation buttons. + +## 5.4.0 release notes + +**March 27, 2019** — The latest release of Sensu Go, version 5.4.0, is now available for download. +This release has some very exciting feature additions, including the introduction of our new homepage. +It also includes support for API pagination to handle large datasets more efficiently and agent buffering for robustness in lower-connectivity situations, along with key bug fixes. + +Read the [upgrade guide][1] to upgrade Sensu to version 5.4.0. + +**NEW FEATURES:** + +- The Sensu dashboard now includes a homepage designed to highlight the most important monitoring data, giving you instant insight into the state of your infrastructure. +read the [web UI docs][23] for a preview. +- The Sensu API now supports pagination using the `limit` and `continue` query parameters, letting you limit your API responses to a maximum number of objects and making it easier to handle large datasets. +Read the [API overview][22] for more information. +- Sensu now surfaces internal metrics using the /metrics API. +Read the [/metrics API documentation][31] for more information. + +**IMPROVEMENTS:** + +- Sensu now lets you specify a separate TLS certificate and key to secure the dashboard. +Read the [backend reference][24] to configure the `dashboard-cert-file` and `dashboard-key-file` options, and check out the [guide to securing Sensu][25] for the complete guide to making your Sensu instance production-ready. +- The Sensu agent events API now queues events before sending them to the backend, making the agent events API more robust and preventing data loss in the event of a loss of connection with the backend or agent shutdown. +Read the [agent reference][26] for more information. + +**FIXES:** + +- The backend now processes events without persisting metrics to etcd. +- The core/v2/events API POST and PUT endpoints now add the current timestamp to new events by default. +- The core/v2/users API endpoints now return a 404 response code if a username cannot be found. +- The sensuctl command line tool now correctly accepts global flags when passed after a subcommand flag (for example, `--format yaml --namespace development`). +- The `sensuctl handler delete` and `sensuctl filter delete` commands now correctly delete resources from the currently configured namespace. +- The agent now terminates consistently on SIGTERM and SIGINT. +- In the event of a loss of connection with the backend, the agent now attempts to reconnect to any backends specified in its configuration. +- The dashboard now handles cases in which the creator of a silence is inaccessible. +- The dashboard event details page now displays "-" in the command field if no command is associated with the event. + +## 5.3.0 release notes + +**March 11, 2019** — The latest release of Sensu Go, version 5.3.0, is now available for download. +This release has some very exciting feature additions and key bug fixes. +Active Directory can be configured as an authentication provider (commercial feature). +Additionally, round robin scheduling has been fully re-implemented and is available for use. + +Read the [upgrade guide][1] to upgrade Sensu to version 5.3.0. + +**NEW FEATURES:** + +- Round robin check scheduling lets you distribute check executions evenly over a group of Sensu agents. +To enable round robin scheduling, set the `round_robin` check attribute to `true`. +Read the [checks reference][18] for more information. +- Sensu now provides [commercial][19] support for using Microsoft Active Directory as an external authentication provider. +Read the [authentication guide][20] to configure Active Directory, and check out the [getting started guide][19] for more information about commercial features. +- The dashboard now features offline state detection and displays an alert banner if the dashboard loses connection to the backend. + +**IMPROVEMENTS:** + +- The agent socket event format now supports the `handlers` attribute, giving you the ability to send socket events to a Sensu pipeline. +Read the [agent reference][21] to learn more about creating and handling monitoring events using the agent socket. +- Assets now feature improved download performance using buffered I/O. +- The sensuctl CLI now uses a 15-second timeout period when connecting to the Sensu backend. +- The dashboard now includes expandable configuration details sections on the check and entity pages. +You can now use the dashboard to review check details like command, subscriptions, and scheduling as well as entity details like platform, IP address, and hostname. + +**SECURITY:** + +- Sensu Go 5.3.0 fixes all known TLS vulnerabilities affecting the backend, including increasing the minimum supported TLS version to 1.2 and removing all ciphers except those with perfect forward secrecy. +- Sensu now enforces uniform TLS configuration for all three backend components: `apid`, `agentd`, and `dashboardd`. +- The backend no longer requires the `trusted-ca-file` configuration option when using TLS. +- The backend no longer loads server TLS configuration for the HTTP client. + +**FIXES:** + +- Sensu can now download assets with download times of more than 30 seconds without timing out. +- The agent now communicates entity subscriptions to the backend in the correct format. +- Sensu no longer includes the `edition` configuration attribute or header. +- DNS resolution in Alpine Linux containers now uses the built-in Go resolver instead of the glibc resolver. +- The `sensuctl user list` command can now output `yaml` and `wrapped-json` formats when used with the `--format` flag. +- The dashboard check details page now displays long commands correctly. +- The dashboard check details page now displays the `timeout` attribute correctly. + +## 5.2.1 release notes + +**February 11, 2019** — The latest release of Sensu Go, version 5.2.1, is now available for download. +This is a stability release with a key bug fix for proxy check functionality. + +Read the [upgrade guide][1] to upgrade Sensu to version 5.2.1. + +**FIXES:** + +- Sensu agents now execute checks for proxy entities at the expected interval. + +## 5.2.0 release notes + +**February 7, 2019** — The latest release of Sensu Go, version 5.2.0, is now available for download. +This release has a ton of exciting content, including the availability of our first enterprise-only features. +For more details on these features, read the [blog post about Sensu Go 5.2.0][14]. +Release 5.2.0 also has some key improvements and fixes: we added support for self-signed CA certificates for sensuctl, check output truncation, and the ability to manage silencing from the event details page in our web UI, to name a few. + +Read the [upgrade guide][1] to upgrade Sensu to version 5.2.0. + +**IMPORTANT:** + +- Due to changes in the release process, Sensu binary-only archives are now named following the pattern `sensu-enterprise-go_5.2.0_$OS_$ARCH.tar.gz`, where `$OS` is the operating system name and `$ARCH` is the CPU architecture. +These archives include all files in the top-level directory. +Read the [installation guide][16] for the latest download links. + +**NEW FEATURES:** + +- Our first enterprise-only features for Sensu Go: [LDAP authentication][96], the [Sensu ServiceNow handler][97], and the [Sensu JIRA handler][98]. +Read the [getting started guide][99]. +- Sensu now provides the option to limit check output size or to drop check outputs following metric extraction. +Read the [checks reference][15] for more information. + +**IMPROVEMENTS:** + +- Sensu now includes support for Debian 8 and 9. +Read the [installation guide][16] to install Sensu for Debian. +- Sensu's binary-only distribution for Linux is now available for `arm64`, `armv5`, `armv6`, `armv7`, and `386` in addition to `amd64`. +Read the [installation guide][16] for download links. +- The Sensu dashboard now provides the ability to silence and unsilence events from the Events page. +- The Sensu dashboard Entity page now displays the platform version and deregistration configuration. +- Sensuctl now supports TLS configuration options, allowing you to use a self-signed certificate without adding it to the operating system's CA store, either by explicitly trusting the signer or by disabling TLS hostname verification. +Read the [sensuctl reference][17] for more information. +- sensuctl now provides action-specific confirmation messages, like `Created`, `Deleted`, and `Updated`. + +**FIXES:** + +- Check TTL failure events now persist through cluster member failures and cluster restarts. +- The Sensu backend now correctly handles errors for missing keepalive events. +- Token-substituted values are now omitted from event data to protect sensitive information. +- Sensu now correctly processes keepalive and check TTL states after entity deletion. +- Sensuctl can now run `sensuctl version` without being configured. +- When disabling users, sensuctl now provides the correct prompt for the action. + +## 5.1.1 release notes + +**January 24, 2019** — The latest patch release of Sensu Go, version 5.1.1, is now available for download. +This release includes some key fixes and improvements, including refactored keepalive functionality with increased reliability. +Additionally, based on community feedback, we have added support for the Sensu agent and sensuctl for 32-bit Windows systems. + +Read the [upgrade guide][1] to upgrade Sensu to version 5.1.1. + +**NEW FEATURES:** + +- Sensu now includes a sensuctl command and API endpoint to test user credentials. +Read the [access control reference][10] and [API docs][11] for more information. + +**IMPROVEMENTS:** + +- The Sensu agent and sensuctl tool are now available for 32-bit Windows. +Read the [installation guide][12] for instructions. +- Keepalive events now include an output attribute specifying the entity name and time last sent. +- The Sensu backend includes refactored authentication and licensing to support future enterprise features. + +**SECURITY:** + +- Sensu 5.1.1 is built with Go version 1.11.5. +Go 1.11.5 addresses a security vulnerability that affects TLS handshakes and JWT tokens. +Read the [CVE][13] for more information. + +**FIXES:** + +- Keepalive events now continue to execute after a Sensu cluster restarts. +- When requested, on-demand check executions now correctly retrieve asset dependencies. +- Checks now maintain a consistent execution schedule after updates to the check definition. +- Proxy check request errors now include the check name and namespace. +- When encountering an invalid line during metric extraction, Sensu now logs an error and continues extraction. +- Sensuctl now returns an error when attempting to delete a non-existent entity. +- Sensuctl now removes the temporary file it creates when executing the `sensuctl edit` command. +- The Sensu dashboard now recovers from errors correctly when shutting down. +- The Sensu dashboard includes better visibility for buttons and menus in the dark theme. + +## 5.1.0 release notes + +**December 19, 2018** — The latest release of Sensu Go, version 5.1.0, is now available for download. +This release includes an important change to the Sensu backend state directory as well as support for Ubuntu 14.04 and some key bug fixes. + +Read the [upgrade guide][1] to upgrade Sensu to version 5.1.0. + +**IMPORTANT:** + +{{% notice note %}} +**NOTE**: This applies only to Sensu backend binaries downloaded from `s3-us-west-2.amazonaws.com/sensu.io/sensu-go`, not to Sensu RPM or DEB packages. +{{% /notice %}} + +- For Sensu backend binaries, the default `state-dir` is now `/var/lib/sensu/sensu-backend` instead of `/var/lib/sensu`. +To upgrade your Sensu backend binary to 5.1.0, make sure your `/etc/sensu/backend.yml` configuration file specifies a `state-dir`. +Read the [upgrade guide][3] for more information. + +**NEW FEATURES:** + +- Sensu [agents][4] now include `trusted-ca-file` and `insecure-skip-tls-verify` configuration options, giving you more flexibility with certificates when connecting agents to the backend over TLS. + +**IMPROVEMENTS:** + +- Sensu now includes support for Ubuntu 14.04. + +**FIXES:** + +- The Sensu backend now successfully connects to an external etcd cluster. +- SysVinit scripts for the Sensu agent and backend now include correct run and log paths. +- Once created, keepalive alerts and check TTL failure events now continue to occur until a successful event is observed. +- When querying for an empty list of assets, sensuctl and the Sensu API now return an empty array instead of null. +- The sensuctl `create` command now successfully creates hooks when provided with the correct definition. +- The Sensu dashboard now renders status icons correctly in Firefox. + +## 5.0.1 release notes + +**December 12, 2018** — Sensu Go 5.0.1 includes our top bug fixes following last week's general availability release. + +Read the [upgrade guide][1] to upgrade Sensu to version 5.0.1. + +**FIXED:** + +- The Sensu backend can now successfully connect to an external etcd cluster. +- The Sensu dashboard now sorts silences in ascending order, correctly displays status values, and reduces shuffling in the event list. +- Sensu agents on Windows now execute command arguments correctly. +- Sensu agents now correctly include environment variables when executing checks. +- Command arguments are no longer escaped on Windows. +- Sensu backend environments now include handler and mutator execution requests. + +## 5.0.0 release notes + +**December 5, 2018** — We're excited to announce the general availability release of Sensu Go! +Sensu Go is the flexible monitoring event pipeline written in Go and designed for container-based and hybrid-cloud infrastructures. +Check out the [Sensu blog][6] for more information about Sensu Go and version 5.0. + +For a complete list of changes from Beta 8-1, review the [Sensu Go changelog][5]. +This page will be the official home for the Sensu Go changelog and release notes. + +To get started with Sensu Go: + +- [Install Sensu Go][8]. +- [Get started monitoring server resources][9]. + +[1]: /sensu-go/latest/operations/maintain-sensu/upgrade/ +[2]: https://semver.org/spec/v2.0.0.html +[3]: /sensu-go/5.1/operations/maintain-sensu/upgrade/#upgrade-sensu-backend-binaries-to-510 +[4]: /sensu-go/5.1/observability-pipeline/observe-schedule/agent/ +[5]: https://www.github.com/sensu/sensu-go/blob/main/CHANGELOG.md#500---2018-11-30 +[6]: https://sensu.io/blog/sensu-go-is-here/ +[8]: /sensu-go/5.0/operations/deploy-sensu/install-sensu/ +[9]: /sensu-go/5.0/observability-pipeline/observe-schedule/monitor-server-resources/ +[10]: /sensu-go/5.1/operations/control-access/rbac/#test-and-change-user-passwords +[11]: /sensu-go/5.1/api/other/auth/ +[12]: /sensu-go/5.1/operations/deploy-sensu/install-sensu/ +[13]: https://nvd.nist.gov/vuln/detail/CVE-2019-6486/ +[14]: https://sensu.io/blog/enterprise-features-in-sensu-go/ +[15]: https://docs.sensu.io/sensu-go/5.2/observability-pipeline/observe-schedule/checks/#check-output-truncation-attributes +[16]: /sensu-go/5.2/operations/deploy-sensu/install-sensu/ +[17]: /sensu-go/5.2/sensuctl/#global-flags +[18]: /sensu-go/5.3/observability-pipeline/observe-schedule/checks#spec-attributes +[19]: /sensu-go/5.3/commercial/ +[20]: /sensu-go/5.3/operations/control-access/ +[21]: /sensu-go/5.3/observability-pipeline/observe-schedule/agent/#creating-monitoring-events-using-the-agent-tcp-and-udp-sockets +[22]: /sensu-go/5.4/api/#pagination +[23]: /sensu-go/5.4/web-ui/ +[24]: /sensu-go/5.4/observability-pipeline/observe-schedule/backend/#web-ui-configuration +[25]: /sensu-go/5.4/operations/deploy-sensu/secure-sensu/ +[26]: /sensu-go/5.4/observability-pipeline/observe-schedule/agent/#events-post +[27]: /sensu-go/5.5/operations/monitor-sensu/tessen/ +[28]: https://sensu.io/blog/announcing-tessen-the-sensu-call-home-service/ +[29]: /sensu-go/5.5/observability-pipeline/observe-schedule/agent/#general-configuration +[30]: /sensu-go/5.5/observability-pipeline/observe-schedule/agent/#creating-monitoring-events-using-the-agent-tcp-and-udp-sockets +[31]: /sensu-go/5.4/api/other/metrics/ +[32]: /sensu-go/5.6/web-ui/ +[33]: /sensu-go/5.6/commercial/ +[34]: /sensu-go/5.6/api/#response-filtering +[35]: /sensu-go/5.6/sensuctl/#filter-responses +[36]: /sensu-go/5.6/api/other/health/ +[37]: /sensu-go/5.6/operations/control-access/ +[38]: /sensu-go/5.6/operations/control-access/ldap-auth/#ldap-binding-attributes +[39]: /sensu-go/5.6/operations/control-access/ad-auth/#ad-binding-attributes +[40]: /sensu-go/5.6/observability-pipeline/observe-schedule/agent/#general-configuration +[41]: /sensu-go/5.7/operations/deploy-sensu/install-sensu/#install-sensu-agents +[42]: /sensu-go/5.7/observability-pipeline/observe-schedule/agent/ +[43]: /sensu-go/5.7/api/#response-filtering +[44]: https://discourse.sensu.io/t/introducing-usage-limits-in-the-sensu-go-free-tier/1156/ +[45]: /sensu-go/5.8/sensuctl/create-manage-resources/#handle-large-datasets +[46]: /sensu-go/5.8/api/other/version/ +[47]: /sensu-go/5.8/observability-pipeline/observe-schedule/backend/#etcd-cipher-suites +[48]: /sensu-go/5.8/operations/monitor-sensu/tessen/ +[49]: /sensu-go/5.8/operations/maintain-sensu/license/ +[50]: /sensu-go/5.8/observability-pipeline/observe-schedule/backend/#advanced-configuration-options +[51]: /sensu-go/5.8/operations/maintain-sensu/upgrade/#upgrade-sensu-clusters-from-570-or-earlier-to-580-or-later +[52]: /sensu-go/5.9/operations/maintain-sensu/upgrade/ +[53]: /sensu-go/5.9/commercial/ +[54]: /sensu-go/5.9/web-ui/ +[55]: /sensu-go/5.9/observability-pipeline/observe-schedule/backend/#event-logging +[56]: /sensu-go/5.9/platforms/ +[57]: /sensu-go/5.9/operations/deploy-sensu/install-sensu/ +[58]: /sensu-go/5.9/observability-pipeline/observe-events/events/#occurrences-and-occurrences-watermark +[59]: /sensu-go/5.9/operations/maintain-sensu/upgrade/#upgrade-sensu-clusters-from-570-or-earlier-to-580-or-later +[60]: /sensu-go/latest/commercial/ +[61]: /sensu-go/5.10/operations/deploy-sensu/datastore/ +[62]: /sensu-go/5.10/api/core/cluster/#the-clusterid-API-endpoint +[63]: /sensu-go/5.10/sensuctl/create-manage-resources/#create-resources-across-namespaces +[64]: /sensu-go/5.10/operations/control-access/rbac/#assigning-group-permissions-across-all-namespaces +[65]: /sensu-go/5.10/web-ui/ +[66]: /sensu-go/5.10/web-ui/search/ +[67]: /sensu-go/5.11/web-ui/ +[68]: /sensu-go/5.11/commercial/ +[69]: /sensu-go/5.11/versions/ +[70]: /sensu-go/5.11/plugins/assets#asset-example-minimum-required-attributes +[71]: /sensu-go/5.11/observability-pipeline/observe-schedule/agent/#disable-assets +[72]: /sensu-go/5.11/sensuctl/create-manage-resources/#delete-resources +[73]: /sensu-go/5.11/platforms/ +[74]: /sensu-go/5.11/operations/control-access/ad-auth/ +[75]: /sensu-go/5.11/api/ +[76]: /sensu-go/5.11/sensuctl/#view-sensuctl-config +[77]: /sensu-go/5.11/observability-pipeline/observe-schedule/backend/#advanced-configuration-options +[78]: /sensu-go/5.12/observability-pipeline/observe-schedule/agent/#allow-list +[79]: /sensu-go/5.14/commercial/ +[80]: /sensu-go/5.14/web-ui/ +[81]: /sensu-go/5.14/operations/deploy-sensu/secure-sensu/#optional-configure-sensu-agent-mtls-authentication +[82]: /sensu-go/5.13/observability-pipeline/observe-entities/entities/ +[83]: /sensu-go/5.14/observability-pipeline/observe-schedule/backend/#advanced-configuration-options +[84]: /sensu-go/5.14/sensuctl/back-up-recover/ +[85]: /sensu-go/5.15/api/enterprise/federation/ +[86]: /sensu-go/5.15/operations/control-access/apikeys/ +[87]: /sensu-go/5.15/operations/control-access/use-apikeys/#sensuctl-management-commands +[88]: /sensu-go/5.15/api/#authenticate-with-an-api-key +[89]: /sensu-go/5.15/sensuctl/ +[90]: https://sensu.io/contact/ +[91]: https://sensu.io/blog/one-year-of-sensu-go/ +[92]: /sensu-go/5.15/api/other/license/ +[93]: /sensu-go/5.15/sensuctl/sensuctl-bonsai#extend-sensuctl-with-commands +[94]: /sensu-go/5.15/observability-pipeline/observe-schedule/checks +[95]: /sensu-go/5.15/commercial/ +[96]: /sensu-go/5.2/operations/control-access/ +[97]: https://bonsai.sensu.io/assets/sensu/sensu-servicenow-handler/ +[98]: https://bonsai.sensu.io/assets/sensu/sensu-jira-handler/ +[99]: /sensu-go/5.2/commercial/ +[100]: /sensu-go/5.16/observability-pipeline/observe-schedule/backend/#etcd-discovery +[101]: /sensu-go/5.16/observability-pipeline/observe-schedule/agent/#keepalive-configuration +[102]: /sensu-go/5.16/observability-pipeline/observe-schedule/backend/#initialization +[103]: /sensu-go/5.16/web-ui/ +[104]: /sensu-go/5.16/ +[105]: /sensu-go/5.16/commercial/ +[106]: /sensu-go/5.17/commercial/ +[107]: /sensu-go/5.17/web-ui/#sign-in-to-the-web-ui +[108]: /sensu-go/5.17/api/enterprise/secrets/ +[109]: /sensu-go/5.17/observability-pipeline/observe-schedule/backend/#docker-initialization +[110]: /sensu-go/5.17/api/#field-selector +[111]: /sensu-go/5.17/operations/control-access/rbac/#cluster-wide-resource-types +[112]: /sensu-go/5.17/api/core/events/#events-post +[113]: /sensu-go/5.17/sensuctl/sensuctl-bonsai/#list-commands +[114]: /sensu-go/5.18/api/core/events/#create-a-new-event +[115]: /sensu-go/5.18/commercial/ +[116]: /sensu-go/5.18/api#label-selector +[117]: /sensu-go/5.18/api#field-selector +[118]: /sensu-go/5.18/api/core/events/ +[119]: /sensu-go/5.18/api/#response-filtering +[120]: /sensu-go/5.18/api/other/auth/#authtest-get +[122]: /sensu-go/5.19/commercial/ +[123]: /sensu-go/5.19/web-ui/search/#save-a-filtered-search +[124]: /sensu-go/5.19/web-ui/ +[125]: /sensu-go/5.19/operations/monitor-sensu/health/ +[126]: /sensu-go/5.19/api/#response-filtering +[127]: /sensu-go/5.19/sensuctl/filter-responses +[128]: /sensu-go/5.19/web-ui/search/ +[129]: /sensu-go/5.19/sensuctl/create-manage-resources#prune-resources +[130]: /sensu-go/5.19/operations/monitor-sensu/tessen/ +[131]: /sensu-go/5.19/observability-pipeline/observe-process/handlers/#pipe-handler-command +[133]: /sensu-go/5.19/platforms/ +[134]: /sensu-go/5.19/operations/deploy-sensu/install-sensu/ +[135]: /sensu-go/5.19/web-ui/ +[136]: /sensu-go/5.19/observability-pipeline/observe-schedule/agent/#assets-burst-limit +[137]: /sensu-go/5.19/observability-pipeline/observe-schedule/backend/#backend-configuration-options +[138]: /sensu-go/5.20/api#field-selector +[139]: /sensu-go/5.20/observability-pipeline/observe-schedule/backend/#log-rotation +[140]: /sensu-go/5.20/operations/maintain-sensu/troubleshoot/#increment-log-level-verbosity +[141]: /sensu-go/5.20/commercial/ +[142]: /sensu-go/5.20/observability-pipeline/observe-schedule/agent/#agent-configuration-options +[143]: /sensu-go/5.20/observability-pipeline/observe-entities/entities/#processes-attributes +[144]: /sensu-go/5.20/sensuctl/create-manage-resources/#supported-resource-types +[145]: /sensu-go/5.20/observability-pipeline/observe-schedule/backend/#configuration-summary +[146]: /sensu-go/5.20/observability-pipeline/observe-schedule/tokens/#manage-assets +[147]: /sensu-go/5.20/observability-pipeline/observe-schedule/tokens/#token-substitution-with-quoted-strings +[148]: /sensu-go/5.20/web-ui/webconfig-reference/ +[149]: /sensu-go/5.20/api/other/license/#get-the-active-license-configuration +[150]: /sensu-go/5.20/operations/maintain-sensu/license/#view-entity-count-and-entity-limit +[151]: /sensu-go/5.20/operations/maintain-sensu/license/#entity-limit +[153]: /sensu-go/5.20/web-ui/ +[154]: /sensu-go/5.20/sensuctl/sensuctl-bonsai/#extend-sensuctl-with-commands +[155]: /sensu-go/5.20/observability-pipeline/observe-schedule/agent/#discover-processes +[156]: /sensu-go/5.21/operations/maintain-sensu/license/#view-entity-count-and-entity-limit +[157]: /sensu-go/5.21/observability-pipeline/observe-schedule/agent/#log-level +[158]: /sensu-go/5.21/commercial/ +[160]: /sensu-go/5.21/observability-pipeline/observe-schedule/backend/#fips-openssl +[161]: /sensu-go/5.21/observability-pipeline/observe-schedule/agent/#fips-openssl +[162]: /sensu-go/6.0/commercial/ +[163]: https://github.com/sensu/web +[164]: /sensu-go/6.0/platforms/#build-from-source +[165]: /sensu-go/6.0/platforms/ +[166]: /sensu-go/6.0/operations/control-access/rbac/#subjects-specification +[167]: /sensu-go/6.0/operations/control-access/rbac/#roleref-specification +[168]: /sensu-go/6.0/observability-pipeline/observe-filter/sensu-query-expressions/#sensucheckdependencies +[169]: /sensu-go/6.0/observability-pipeline/observe-filter/filters/#build-event-filter-expressions-with-javascript-execution-functions +[170]: /sensu-go/6.0/operations/maintain-sensu/upgrade/#upgrade-to-sensu-go-60-from-a-5x-deployment +[171]: /sensu-go/6.0/observability-pipeline/observe-entities/entities/#create-and-manage-agent-entities +[172]: /sensu-go/6.1/commercial/ +[173]: /sensu-go/6.1/observability-pipeline/observe-schedule/backend/#api-request-limit +[174]: /sensu-go/6.1/api/ +[175]: /sensu-go/6.1/operations/manage-secrets/secrets-management/#use-hashicorp-vault-for-secrets-management +[176]: /sensu-go/6.1/api/enterprise/authproviders/#authproviders-get-specification +[177]: /sensu-go/6.1/api/enterprise/secrets/#providers-get-specification +[178]: /sensu-go/6.1/web-ui/search/ +[179]: /sensu-go/6.1/operations/deploy-sensu/datastore/#strict-attribute +[180]: /sensu-go/6.1/operations/control-access/oidc-auth/#oidc-spec-attributes +[181]: /sensu-go/6.1/operations/deploy-sensu/datastore/#spec-attributes +[182]: /sensu-go/6.1/observability-pipeline/observe-schedule/checks#output-metric-tags +[183]: https://bonsai.sensu.io/assets/sensu/sensu-saltstack-handler +[184]: https://bonsai.sensu.io/assets/sensu/sensu-elasticsearch-handler +[185]: https://bonsai.sensu.io/assets/sensu/sensu-rundeck-handler +[186]: https://bonsai.sensu.io/assets/sensu/sensu-kubernetes-events +[187]: https://bonsai.sensu.io/assets/sensu/sensu-timescaledb-handler +[188]: https://github.com/sensu/grafana-sensu-go-datasource +[189]: https://github.com/sensu/grafana-sensu-go-datasource/releases/tag/1.1.0 +[190]: /sensu-go/6.1/operations/control-access/rbac/#rule-attributes +[191]: /sensu-go/6.1/sensuctl/back-up-recover/ +[192]: /sensu-go/6.1/sensuctl/create-manage-resources/#prune-resources +[193]: /sensu-go/6.2/commercial/ +[194]: /sensu-go/6.2/api/enterprise/prune/ +[195]: /sensu-go/6.2/sensuctl/create-manage-resources/#prune-resources +[196]: /sensu-go/6.2/api/other/metrics/ +[197]: /sensu-go/6.2/observability-pipeline/observe-schedule/checks/#scheduler-attribute +[198]: /sensu-go/6.2/observability-pipeline/observe-events/events/#sequence-attribute +[199]: /sensu-go/6.2/operations/control-access/ldap-auth/ +[200]: /sensu-go/6.2/sensuctl/create-manage-resources/#sensuctl-prune-flags +[201]: /sensu-go/6.2/operations/deploy-sensu/datastore/#round-robin-postgresql +[202]: /sensu-go/6.2/sensuctl/#first-time-setup-and-authentication +[203]: /sensu-go/6.2/observability-pipeline/observe-schedule/agent/#agent-managed-entity +[204]: /sensu-go/6.2/observability-pipeline/observe-entities/entities/#manage-agent-entities-via-the-agent +[205]: /sensu-go/6.2/observability-pipeline/observe-schedule/agent/#agent-configuration-options +[206]: /sensu-go/5.21/observability-pipeline/observe-schedule/backend/#log-rotation +[207]: /sensu-go/6.3/commercial/ +[208]: /sensu-go/6.3/observability-pipeline/observe-schedule/backend/#agent-burst-limit +[209]: /sensu-go/6.3/observability-pipeline/observe-schedule/backend/#agent-rate-limit +[210]: /sensu-go/6.3/observability-pipeline/observe-schedule/business-service-monitoring/ +[211]: /sensu-go/6.3/observability-pipeline/observe-schedule/rule-templates/#built-in-rule-template-aggregate +[212]: /sensu-go/6.3/api/other/health/#get-health-data-for-your-agent-transport +[213]: /sensu-go/6.3/observability-pipeline/observe-entities/#service-entities +[214]: /sensu-go/6.3/sensuctl/#global-flags +[215]: /sensu-go/6.4/commercial/ +[216]: /sensu-go/6.4/platforms/#macos +[217]: /sensu-go/6.4/observability-pipeline/observe-schedule/backend/#etcd-log-level +[218]: /sensu-go/6.4/observability-pipeline/observe-schedule/backend/#initialization-timeout-and-wait-flags +[219]: https://etcd.io/docs/v3.5/metrics/etcd-metrics-latest.txt +[220]: /sensu-go/6.4/web-ui/webconfig-reference/#sign-in-message +[221]: /sensu-go/6.4/web-ui/webconfig-reference/#page-preferences-attributes +[222]: /sensu-go/6.4/operations/maintain-sensu/upgrade/#upgrade-to-sensu-go-640-from-any-previous-version +[223]: /sensu-go/6.3/web-ui/webconfig-reference/#default-preferences-attributes +[224]: /sensu-go/5.20/observability-pipeline/observe-schedule/backend/#metrics-refresh-interval +[225]: /sensu-go/6.4/observability-pipeline/observe-schedule/agent/#log-level +[226]: /sensu-go/6.4/observability-pipeline/observe-schedule/backend/#event-log-parallel-encoders +[227]: /sensu-go/6.4/api/other/metrics/ +[228]: /sensu-go/6.4/observability-pipeline/observe-schedule/backend/#event-logging +[229]: /sensu-go/5.16/observability-pipeline/observe-schedule/backend/#etcd-discovery-srv +[229]: /sensu-go/6.5/commercial/ +[230]: /sensu-go/6.5/observability-pipeline/observe-process/sumo-logic-metrics-handlers/ +[231]: /sensu-go/6.5/observability-pipeline/observe-process/tcp-stream-handlers/ +[232]: /sensu-go/6.5/api/core/pipelines/ +[233]: /sensu-go/6.5/observability-pipeline/observe-process/pipelines/ +[234]: /sensu-go/6.5/api/enterprise/pipeline/ +[235]: /sensu-go/6.5/sensuctl/create-manage-resources/#manage-resources +[236]: /sensu-go/6.5/observability-pipeline/observe-schedule/checks/#pipelines-attribute +[237]: /sensu-go/6.5/observability-pipeline/observe-schedule/backend/#event-logging +[238]: /sensu-go/6.5/observability-pipeline/observe-schedule/backend/#platform-metrics-logging +[239]: https://github.com/dgrijalva/jwt-go +[240]: https://github.com/golang-jwt/jwt +[241]: https://nvd.nist.gov/vuln/detail/CVE-2020-26160 +[242]: /sensu-go/6.5/sensuctl/environment-variables/#export-environment-variables-with-sensuctl-env +[243]: /sensu-go/6.5/sensuctl/environment-variables/#set-environment-variables-for-a-single-command +[244]: /sensu-go/6.5/sensuctl/environment-variables/#set-environment-variables-with-sensuctl-configure +[245]: /sensu-go/6.5/operations/deploy-sensu/cluster-sensu/#authenticate-with-username-and-password-for-external-etcd +[246]: /sensu-go/6.5/observability-pipeline/observe-transform/mutators/#javascript-mutators +[247]: /sensu-go/6.5/sensu-plus/ +[248]: /sensu-go/6.5/observability-pipeline/observe-schedule/backend/#add-api-key-for-initialization +[249]: /sensu-go/6.5/web-ui/view-manage-resources/#view-resource-data-in-the-web-ui +[250]: /sensu-go/6.5/web-ui/view-manage-resources/#execute-checks-on-demand +[251]: /sensu-go/6.5/observability-pipeline/observe-events/events/#processedby-attribute +[253]: /sensu-go/6.5/observability-pipeline/observe-schedule/backend/#ignore-already-initialized +[254]: /sensu-go/6.5/observability-pipeline/observe-transform/mutators/#env-vars-attribute +[255]: #652-release-notes +[256]: /sensu-go/6.5/observability-pipeline/observe-schedule/backend/#api-write-timeout +[257]: /sensu-go/6.5/observability-pipeline/observe-schedule/backend/#dashboard-write-timeout +[258]: /sensu-go/6.6/observability-pipeline/observe-schedule/backend/#platform-metrics-logging +[259]: /sensu-go/6.6/commercial/ +[260]: /sensu-go/6.6/observability-pipeline/observe-schedule/backend/#datastore-and-cluster-configuration +[261]: /sensu-go/6.6/web-ui/view-manage-resources/#manage-entities +[262]: /sensu-go/6.6/observability-pipeline/observe-schedule/backend/#etcd-client-log-level +[263]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options +[264]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security +[265]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Content-Type-Options +[266]: /sensu-go/6.6/web-ui/search/#events-and-entities-search-limits +[267]: /sensu-go/latest/operations/deploy-sensu/datastore/#strict-attribute +[268]: /sensu-go/6.7/commercial/ +[269]: /sensu-go/6.7/catalog/sensu-catalog/ +[270]: /sensu-go/6.7/web-ui/ +[271]: /sensu-go/6.7/sensu-plus/ +[272]: /sensu-go/6.7/observability-pipeline/observe-schedule/backend/#etcd-election-timeout +[273]: /sensu-go/6.7/observability-pipeline/observe-schedule/backend/#etcd-heartbeat-interval +[274]: /sensu-go/6.7/observability-pipeline/observe-filter/sensu-query-expressions/#sensucheckdependencies +[275]: /sensu-go/6.7/observability-pipeline/observe-process/#keepalive-pipelines +[276]: /sensu-go/6.7/observability-pipeline/observe-schedule/agent/#keepalive-pipelines +[277]: /sensu-go/6.7/observability-pipeline/observe-schedule/checks/#subdues +[278]: /sensu-go/6.7/observability-pipeline/observe-entities/entities/#backend-entities +[279]: /sensu-go/6.7/operations/control-access/namespaces/#default-namespaces +[280]: /sensu-go/6.7/operations/deploy-sensu/datastore/#round-robin-postgresql +[281]: /sensu-go/6.7/observability-pipeline/observe-schedule/business-service-monitoring/ +[282]: /sensu-go/6.7/observability-pipeline/observe-schedule/backend/#platform-metrics-logging +[283]: /sensu-go/6.7/observability-pipeline/observe-process/tcp-stream-handlers/ +[284]: /sensu-go/6.7/observability-pipeline/observe-filter/sensu-query-expressions/#sensucheckdependencies-custom-function +[285]: /sensu-go/6.7/observability-pipeline/observe-schedule/metrics/#metric-threshold-evaluation +[286]: /sensu-go/6.7/web-ui/view-manage-resources/#view-resource-data-in-the-web-ui +[287]: /sensu-go/6.7/web-ui/webconfig-reference/#serialization_format +[288]: /sensu-go/6.7/web-ui/webconfig-reference/#sign-in-message +[289]: /sensu-go/6.7/catalog/sensu-catalog/#duplicate-integrations-and-existing-resources +[290]: /sensu-go/6.7/catalog/sensu-catalog/ +[291]: /sensu-go/6.7/observability-pipeline/observe-events/events/#check-scope +[292]: /sensu-go/5.16/observability-pipeline/observe-schedule/backend/#etcd-discovery-srv +[293]: https://nvd.nist.gov/vuln/detail/CVE-2022-37315 +[294]: /sensu-go/6.7/web-ui/webconfig-reference/#license_expiry_reminder +[295]: /sensu-go/6.8/commercial/ +[296]: /sensu-go/6.8/web-ui/#view-system-information +[297]: /sensu-go/6.8/web-ui/view-manage-resources/#manage-configuration-resources +[298]: /sensu-go/6.8/observability-pipeline/observe-events/events/#issued_attribute +[299]: /sensu-go/6.8/api/other/ready/ +[300]: /sensu-go/6.8/observability-pipeline/observe-schedule/backend/#api-serve-wait-time +[301]: /sensu-go/6.8/observability-pipeline/observe-schedule/backend/#agent-serve-wait-time +[302]: /sensu-go/6.8/observability-pipeline/observe-schedule/checks/#check-output-truncation-attributes +[303]: /sensu-go/6.9/commercial/ +[304]: /sensu-go/6.9/operations/manage-secrets/secrets-providers/#cyberarkprovider-spec-attributes +[305]: /sensu-go/6.9/operations/manage-secrets/secrets-management/#use-cyberark-conjur-for-secrets-management +[306]: https://devhub.checkmarx.com/cve-details/CVE-2022-37315/?utm_source=jetbrains&utm_medium=referral&utm_campaign=goland&utm_term=go +[307]: /sensu-go/6.10/commercial/ +[308]: /sensu-go/6.11/commercial/ +[309]: https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/4407 +[310]: /sensu-go/6.11/platforms/#federal-information-processing-standard-fips-compliance +[311]: /sensu-go/6.12/commercial/ +[312]: /sensu-go/6.12/observability-pipeline/observe-schedule/backend/#max-silenced-expiry-time-allowed +[313]: /sensu-go/6.12/observability-pipeline/observe-schedule/backend/#default-silenced-expiry-time-attribute +[314]: /sensu-go/6.12/observability-pipeline/observe-schedule/backend/#enable-cert-revocation-check + diff --git a/content/sensu-go/6.12/sensu-plus.md b/content/sensu-go/6.12/sensu-plus.md new file mode 100644 index 0000000000..4462171d0a --- /dev/null +++ b/content/sensu-go/6.12/sensu-plus.md @@ -0,0 +1,435 @@ +--- +title: "Sensu Plus" +description: "Deploy the Sensu Plus turnkey integration to send metrics to Sumo Logic and extract insights from your Sensu observability data." +version: "6.12" +weight: -20 +offline: true +toc: true +product: "Sensu Go" +menu: "sensu-go-6.12" +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access Sensu Plus in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../commercial/). +{{% /notice %}} + +Sensu Plus is a built-in integration for transmitting your Sensu observability data to the Sumo Logic Continuous Intelligence Platform™ via a Sumo Logic [HTTP Logs and Metrics Source][1] (an endpoint for receiving data). +In Sumo Logic, you can configure customized interactive dashboards and analytics tools to gain better visibility into your Sensu data — read [Introducing Sensu Plus][14] for more information. + +**If you completed Sumo Logic setup in the Sensu web UI**, [finish the configuration process][15] to create the Sensu resources you need to start sending observability event data to Sumo Logic. + +If you did **not** use the Sensu web UI to set up a Sumo Logic account, follow the [manual setup process for Sensu Plus][19]. + +## Finish configuration after web UI setup + +In the Sensu web UI, you already set up a Sumo Logic account and HTTP Logs and Metrics Source endpoint for receiving data. +To finish your configuration, you need the **SOURCE URL** for your endpoint, which you can copy from the last page in the web UI dialog. + +Follow the steps in this section to create a Sensu handler, pipeline, and check to transmit your Sensu data in Sumo Logic. + +### Create a handler in Sensu + +Create a Sumo Logic metrics handler to send your Sensu observability data to your new Sumo Logic HTTP Logs and Metrics Source. +[Sumo Logic metrics handlers][5] provide a persistent connection to transmit Sensu observability data, which helps prevent the data bottlenecks you may experience with traditional handlers. + +{{% notice note %}} +**NOTE**: Sumo Logic metrics handlers only accept metrics events. +To send status events, use the [Sensu Sumo Logic Handler integration](../plugins/featured-integrations/sumologic/) instead. +{{% /notice %}} + +For a Sumo Logic metrics handler, the resource definition must use the URL for your HTTP Logs and Metrics Source as the value for the `url` attribute. + +Here is an example Sumo Logic Metrics Handler definition. +Before you run the command to add this handler, replace the `url` example value with the URL for your Sumo Logic HTTP Logs and Metrics Source: + +{{< language-toggle >}} + +{{< code text "YML" >}} +cat << EOF | sensuctl create +--- +type: SumoLogicMetricsHandler +api_version: pipeline/v1 +metadata: + name: sumo_logic_http_metrics +spec: + url: "https://collectors.sumologic.com/receiver/v1/http/xxxxxxxx" + max_connections: 10 + timeout: 10s +EOF +{{< /code >}} + +{{< code text "JSON" >}} +cat << EOF | sensuctl create +{ + "type": "SumoLogicMetricsHandler", + "api_version": "pipeline/v1", + "metadata": { + "name": "sumo_logic_http_metrics" + }, + "spec": { + "url": "https://collectors.sumologic.com/receiver/v1/http/xxxxxxxx", + "max_connections": 10, + "timeout": "10s" + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + +If you prefer, you can configure your Sumo Logic HTTP Logs and Metrics Source URL as a [secret][6] with Sensu's [`Env` secrets provider][7] to avoid exposing the URL in your handler definition. +This example shows the same definition with the URL referenced as a secret instead: + +{{< language-toggle >}} + +{{< code text "YML" >}} +cat << EOF | sensuctl create +--- +type: SumoLogicMetricsHandler +api_version: pipeline/v1 +metadata: + name: sumo_logic_http_metrics +spec: + url: $SUMO_LOGIC_SOURCE_URL + secrets: + - name: SUMO_LOGIC_SOURCE_URL + secret: sumologic_metrics_us1 + max_connections: 10 + timeout: 10s +EOF +{{< /code >}} + +{{< code text "JSON" >}} +cat << EOF | sensuctl create +{ + "type": "SumoLogicMetricsHandler", + "api_version": "pipeline/v1", + "metadata": { + "name": "sumo_logic_http_metrics" + }, + "spec": { + "url": "$SUMO_LOGIC_SOURCE_URL", + "secrets": [ + { + "name": "SUMO_LOGIC_SOURCE_URL", + "secret": "sumologic_metrics_us1" + } + ], + "max_connections": 10, + "timeout": "10s" + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + +### Configure a pipeline + +Sensu [pipelines][8] use event filters, mutators, and handlers as the building blocks for event processing workflows. +With your handler definition configured, you’re ready to create a pipeline with a workflow that references your sumo_logic_http_metrics handler. + +To configure event processing via your sumo_logic_http_metrics handler, add this example pipeline definition. +This pipeline includes a workflow with your sumo_logic_http_metrics handler, along with Sensu's built-in [has_metrics event filter][12] to ensure that the workflow only processes events that contain metrics: + +{{< language-toggle >}} + +{{< code text "YML" >}} +cat << EOF | sensuctl create +--- +type: Pipeline +api_version: core/v2 +metadata: + name: sensu_to_sumo +spec: + workflows: + - name: metrics_to_sumologic + filters: + - name: has_metrics + type: EventFilter + api_version: core/v2 + handler: + name: sumo_logic_http_metrics + type: SumoLogicMetricsHandler + api_version: pipeline/v1 +EOF +{{< /code >}} + +{{< code text "JSON" >}} +cat << EOF | sensuctl create +{ + "type": "Pipeline", + "api_version": "core/v2", + "metadata": { + "name": "sensu_to_sumo" + }, + "spec": { + "workflows": [ + { + "name": "metrics_to_sumologic", + "filters": [ + { + "name": "has_metrics", + "type": "EventFilter", + "api_version": "core/v2" + } + ], + "handler": { + "name": "sumo_logic_http_metrics", + "type": "SumoLogicMetricsHandler", + "api_version": "pipeline/v1" + } + } + ] + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + +### Add a Sensu check + +Your pipeline resource is now properly configured, but it’s not processing any events because no Sensu [checks][9] are sending events to it. +To get your Sensu observability data flowing through the new pipeline, add the pipeline by reference in at least one check definition. + +This example check definition uses the [sensu/system-check][13] dynamic runtime asset. +[Dynamic runtime assets][20] are shareable, reusable packages that make it easier to deploy Sensu plugins. + +Follow these steps to configure the required system check: + +1. Add the [sensu/system-check][13] dynamic runtime asset: +{{< code shell >}} +sensuctl asset add sensu/system-check:0.1.1 -r system-check +{{< /code >}} + +2. Update at least one Sensu entity to use the `system` subscription. +In the following command, replace `` with the name of the entity on your system. +Then, run: +{{< code shell >}} +sensuctl entity update +{{< /code >}} + + - For `Entity Class`, press enter. + - For `Subscriptions`, type `system` and press enter. + +3. Add the following check definition: + + {{< language-toggle >}} + +{{< code text "YML" >}} +cat << EOF | sensuctl create +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: system-check +spec: + command: system-check + runtime_assets: + - system-check + subscriptions: + - system + interval: 10 + timeout: 5 + publish: true + pipelines: + - type: Pipeline + api_version: core/v2 + name: sensu_to_sumo + output_metric_format: prometheus_text + output_metric_tags: + - name: entity + value: "{{ .name }}" + - name: namespace + value: "{{ .namespace }}" + - name: os + value: "{{ .system.os }}" + - name: platform + value: "{{ .system.platform }}" +EOF +{{< /code >}} + +{{< code text "JSON" >}} +cat << EOF | sensuctl create +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "name": "system-check" + }, + "spec": { + "command": "system-check", + "runtime_assets": [ + "system-check" + ], + "subscriptions": [ + "system" + ], + "interval": 10, + "timeout": 5, + "publish": true, + "pipelines": [ + { + "type": "Pipeline", + "api_version": "core/v2", + "name": "sensu_to_sumo" + } + ], + "output_metric_format": "prometheus_text", + "output_metric_tags": [ + { + "name": "entity", + "value": "{{ .name }}" + }, + { + "name": "namespace", + "value": "{{ .namespace }}" + }, + { + "name": "os", + "value": "{{ .system.os }}" + }, + { + "name": "platform", + "value": "{{ .system.platform }}" + } + ] + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + +This check will collect baseline system metrics in Prometheus format for all entities that include the `system` subscription and send the events to Sumo Logic via your sensu_to_sumo pipeline resource. + +{{% notice note %}} +**NOTE**: Sumo Logic metrics handlers only accept metrics events, so you must use a check that produces metrics. +If your check produces status events, use the [Sensu Sumo Logic Handler integration](../plugins/featured-integrations/sumologic/) to create a traditional Sensu handler rather than the Sumo Logic metrics handler. +{{% /notice %}} + +### View your Sensu data in Sumo Logic + +During the web UI setup process, Sensu added two custom dashboards as a starting point for viewing your observability event data. +The two new dashboards will be listed in the Sensu folder in the left-navigation menu: + +{{< figure src="/images/go/sensu_plus/sensu_dashboards_in_sumo_logic.png" alt="Sensu Overview and Sensu Entity Details dashboards listed in the Sumo Logic left-navigation menu" link="/images/go/sensu_plus/sensu_dashboards_in_sumo_logic.png" target="_blank" >}} + +Click a dashboard name to view your Sensu observability data. + +It may take a few moments for your data to appear in Sumo Logic. +The Sensu Overview and Sensu Entity Details dashboards will begin to display your data: + +{{< figure src="/images/go/sensu_plus/sensu_entity_details_dashboard_sumo_logic.png" alt="Data beginning to populate in the Sensu Entity Details dashboard in Sumo Logic" link="/images/go/sensu_plus/sensu_entity_details_dashboard_sumo_logic.png" target="_blank" >}} + +## Manually set up Sensu Plus + +This section explains how to set up Sensu Plus manually, without using the Sensu web UI. + +First, [create a new Sumo Logic account][2] or log in to your existing account. + +Then follow the steps below to create a Sumo Logic [HTTP Logs and Metrics Source][1] (an endpoint for receiving data), the Sensu resources that collect and process the data, and two dashboards for viewing your observability event data in Sumo Logic. + +### Set up an HTTP Logs and Metrics Source + +Create a Sumo Logic HTTP Logs and Metrics Source to collect your Sensu observability data: + +1. In the Sumo Logic left-navigation menu, click **Manage Data** and then **Collection**. + + {{< figure src="/images/go/sensu_plus/manage_data_collection.png" alt="Open the Collections tab" link="/images/go/sensu_plus/manage_data_collection.png" target="_blank" >}} + +2. At the top-right of the Collection tab, click **Add Collector**. + + {{< figure src="/images/go/sensu_plus/add_collector.png" alt="Add a Sumo Logic collector" link="/images/go/sensu_plus/add_collector.png" target="_blank" >}} + +3. In the Click Selector Type modal window, click **Hosted Collector**. + + {{< figure src="/images/go/sensu_plus/hosted_collector_option.png" alt="Select the hosted collector option" link="/images/go/sensu_plus/hosted_collector_option.png" target="_blank" >}} + +4. In the Add Hosted Collector modal window: + - Type **sensu** in the Name field. + - Click **Save**. + + {{< figure src="/images/go/sensu_plus/add_hosted_collector.png" alt="Name the hosted collector" link="/images/go/sensu_plus/add_hosted_collector.png" target="_blank" >}} + +5. In the Confirm prompt, click **OK**. + + {{< figure src="/images/go/sensu_plus/confirm_prompt.png" alt="Confirm your hosted collector configuration" link="/images/go/sensu_plus/confirm_prompt.png" target="_blank" >}} + +6. Under Cloud APIs, click **HTTP Logs & Metrics**. + + {{< figure src="/images/go/sensu_plus/cloud_apis_http_logs_and_metrics.png" alt="Select the HTTP Logs & Metrics source" link="/images/go/sensu_plus/cloud_apis_http_logs_and_metrics.png" target="_blank" >}} + +7. In the HTTP Logs & Metrics form: + - Type **sensu-http** in the Name field. + - Type **sensu-events** in the Source Category field. + - Click **Save**. + + {{< figure src="/images/go/sensu_plus/http_logs_and_metrics_source.png" alt="Select options for HTTP Logs & Metrics source" link="/images/go/sensu_plus/http_logs_and_metrics_source.png" target="_blank" >}} + +8. In the HTTP Source Address prompt, copy the listed URL and click OK. +You will use this URL as the value for the `url` attribute in your Sensu [handler][3] definition. + + {{< figure src="/images/go/sensu_plus/http_source_address_url.png" alt="Retrieve the HTTP Source Address URL" link="/images/go/sensu_plus/http_source_address_url.png" target="_blank" >}} + + +### Import Sumo Logic dashboards + +To view your Sensu observability data in Sumo Logic, you can configure [Sumo Logic dashboards][4] in any way you wish. +As a starting point, follow these instructions to import two dashboards, Sensu Overview and Sensu Entity Details: + +1. On your [Sumo Logic home page][10], click the **Personal** tab in the left-navigation menu. +Click the options icon for the folder where you want to import your Sensu data and select **Import**. + + {{< figure src="/images/go/sensu_plus/personal_folder_import.png" alt="Navigate to the folder where you want to import Sensu data" link="/images/go/sensu_plus/personal_folder_import.png" target="_blank" >}} + +2. In the Import Content modal window: + - Type "Sensu" in the **Name** field. + - Copy the [dashboard configuration JSON](../files/sensu-plus-dashboard-config.json) (download) and paste it into the **JSON** field: + + {{< figure src="/images/go/sensu_plus/import_content.png" alt="Import Content modal window for dashboards" link="/images/go/sensu_plus/import_content.png" target="_blank" >}} + +3. Scroll to the bottom of the Import Content modal window and click **Import**. +The two new dashboards will be listed in the Sensu folder in the left-navigation menu: + + {{< figure src="/images/go/sensu_plus/sensu_dashboards_in_sumo_logic.png" alt="Sensu Overview and Sensu Entity Details dashboards listed in the Sumo Logic left-navigation menu" link="/images/go/sensu_plus/sensu_dashboards_in_sumo_logic.png" target="_blank" >}} + +After you create a Sensu handler, pipeline, and check in the next section, you will be able to click a dashboard name to view your Sensu observability data. + +### Create Sensu resources + +With your dashboards set up, you're ready to configure a Sensu handler, pipeline, and check. +To create the Sensu resources, follow the same instructions as users who started in the web UI: + +- [Create a handler in Sensu][3] +- [Configure a pipeline][16] +- [Add a Sensu check][17] + +After you add the check, it may take a few moments for your data to appear in Sumo Logic. +The Sensu Overview and Sensu Entity Details dashboards will begin to display your data: + +{{< figure src="/images/go/sensu_plus/sensu_entity_details_dashboard_sumo_logic.png" alt="Data beginning to populate in the Sensu Entity Details dashboard in Sumo Logic" link="/images/go/sensu_plus/sensu_entity_details_dashboard_sumo_logic.png" target="_blank" >}} + + +[1]: https://help.sumologic.com/03Send-Data/Sources/02Sources-for-Hosted-Collectors/HTTP-Source +[2]: https://www.sumologic.com/sign-up/?utm_source=sensudocs&utm_medium=sensuwebsite +[3]: #create-a-handler-in-sensu +[4]: https://help.sumologic.com/Visualizations-and-Alerts/Dashboards +[5]: ../observability-pipeline/observe-process/sumo-logic-metrics-handlers +[6]: ../operations/manage-secrets/secrets/ +[7]: ../operations/manage-secrets/secrets-providers/#env-secrets-provider-example +[8]: ../observability-pipeline/observe-process/pipelines/ +[9]: ../observability-pipeline/observe-schedule/checks/ +[10]: https://service.sumologic.com/ui/#/home +[11]: ../plugins/featured-integrations/sumologic/ +[12]: ../observability-pipeline/observe-filter/filters/#built-in-filter-has_metrics +[13]: https://bonsai.sensu.io/assets/sensu/system-check +[14]: https://www.sumologic.com/blog/introducing-sensu-plus/ +[15]: #finish-configuration-after-web-ui-setup +[16]: #configure-a-pipeline +[17]: #add-a-sensu-check +[18]: #import-sumo-logic-dashboards +[19]: #manually-set-up-sensu-plus +[20]: ../plugins/assets/ diff --git a/content/sensu-go/6.12/sensuctl/_index.md b/content/sensu-go/6.12/sensuctl/_index.md new file mode 100644 index 0000000000..9b1f9aafda --- /dev/null +++ b/content/sensu-go/6.12/sensuctl/_index.md @@ -0,0 +1,525 @@ +--- +title: "Sensuctl CLI" +description: "Use the sensuctl command line tool to create, read, update, and delete Sensu events, entities, and resources by calling Sensu’s underlying API." +weight: 40 +product: "Sensu Go" +version: "6.12" +layout: "single" +menu: + sensu-go-6.12: + identifier: sensuctl +--- + +Sensuctl is the command line tool for managing resources within Sensu. +It works by calling Sensu's underlying API to create, read, update, and delete events, entities, and resources. + +Sensuctl is available for Linux, macOS, and Windows. +For Windows operating systems, sensuctl uses `cmd.exe` for the execution environment. +For all other operating systems, sensuctl uses the Bourne shell (sh). + +Read [Install Sensu][2] to install and configure sensuctl. + +## First-time setup and authentication + +To log in to sensuctl and connect to the Sensu backend by following interactive prompts, run: + +{{< code shell >}} +sensuctl configure +{{< /code >}} + +The `sensuctl configure` command starts the prompts for interactive setup. +The first prompt is for the authentication method you wish to use: username/password or OIDC. + +Sensuctl uses your username and password or OIDC credentials to obtain access and refresh tokens via the Sensu [/auth API][14]. +The access and refresh tokens are HMAC-SHA256 [JSON Web Tokens (JWTs)][16] that Sensu issues to record the details of users' authenticated Sensu sessions. +The backend digitally signs these tokens, and the tokens can't be changed without invalidating the signature. + +Upon successful authentication, sensuctl stores the access and refresh tokens in a `cluster` configuration file under the current user's home directory. +For example, on Unix systems, sensuctl stores the tokens in `$HOME/.config/sensu/sensuctl/cluster`. + +The `sensuctl configure` interactive prompts require you to select an authentication method and enter the [Sensu backend URL][6], namespace, and preferred output format. + +### Username/password authentication + +If you select username/password authentication, you will be prompted to enter your [username and password Sensu access credentials][8]. + +Username/password authentication applies to the following authentication providers: + +- [Built-in basic authentication][11] +- [Lightweight Directory Access Protocol (LDAP) authentication][17] ([commercial feature][19]) +- [Active Directory (AD) authentication][18] ([commercial feature][19]) + +This example shows the `sensuctl configure` interactive dialog for the username/password authentication method: + +{{< code text >}} +Authentication method: username/password +Sensu Backend API URL: http://127.0.0.1:8080 +Namespace: default +Preferred output format: tabular +Username: +Password: +{{< /code >}} + +### OIDC authentication + +This example shows the `sensuctl configure` interactive dialog if you select the OIDC authentication method: + +{{< code text >}} +Authentication method: OIDC +Sensu Backend API URL: http://127.0.0.1:8080 +Namespace: default +Preferred output format: tabular +Launching browser to complete the login via your OIDC provider at following URL: + + http://127.0.0.1:8080/api/enterprise/authentication/v2/oidc/authorize?callback=http%3A%2F%2Flocalhost%3A8000%2Fcallback + +You may also manually open this URL. Waiting for callback... +{{< /code >}} + +If you are using a desktop, a browser should open to allow you to authenticate and log in via your OIDC provider. +If a browser does not open, launch a browser and go to the OIDC URL listed at the end of the `sensuctl configure` interactive dialog to complete authentication and log in via your OIDC provider. + +{{% notice note %}} +**NOTE**: You can also use [`sensuctl login oidc`](../operations/control-access/oidc-auth/#use-sensuctl-to-login-with-oidc) to log in to sensuctl with OIDC. +{{% /notice %}} + +## Use flags to configure sensuctl in non-interactive mode + +Run `sensuctl configure` non-interactively by adding the `-n` (`--non-interactive`) flag. +For example, the following command configures sensuctl with the same values used in the [username/password interactive example][26]: + +{{< code shell >}} +sensuctl configure -n --url http://127.0.0.1:8080 --format tabular --username --password '' +{{< /code >}} + +Run `sensuctl configure -h` to view command-specific and global flags that you can use to set up sensuctl when you bypass interactive mode: + +{{< code text >}} +Initialize sensuctl configuration + +Usage: sensuctl configure [flags] + +Flags: + --format string preferred output format (default "tabular") + -h, --help help for configure + -n, --non-interactive do not administer interactive questionnaire + --oidc use an OIDC provider for authentication + --password string password + --port int port for local HTTP web server used for OAuth 2 callback during OIDC authentication (default 8000) + --url string the sensu backend url (default "http://localhost:8080") + --username string username + +Global Flags: + --api-key string API key to use for authentication + --api-url string host URL of Sensu installation + --cache-dir string path to directory containing cache & temporary files (default "/Users/hillaryfraley/Library/Caches/sensu/sensuctl") + --config-dir string path to directory containing configuration files (default "/Users/hillaryfraley/.config/sensu/sensuctl") + --insecure-skip-tls-verify skip TLS certificate verification (not recommended!) + --namespace string namespace in which we perform actions (default "default") + --timeout duration timeout when communicating with sensu backend (default 15s) + --trusted-ca-file string TLS CA certificate bundle in PEM format +{{< /code >}} + +## Username, password, and namespace + +The [Sensu backend installation][10] process creates an administrator username and password and a `default` [namespace][27]. + +{{% notice note %}} +**NOTE**: For a **new** installation, you can set administrator credentials with environment variables during [initialization](../observability-pipeline/observe-schedule/backend/#initialization). +If you are using Docker and you do not include the environment variables to set administrator credentials, the backend will initialize with the default username (`admin`) and password (`P@ssw0rd!`). +{{% /notice %}} + +Your ability to get, list, create, update, and delete resources with sensuctl depends on the permissions assigned to your Sensu user. +For more information about configuring Sensu access control, read the [role-based access control (RBAC) reference][1]. + +### Change the admin user's password + +After you [configure sensuctl and authenticate][12], you can change the admin user's password. +Run: + +{{< code shell >}} +sensuctl user change-password --interactive +{{< /code >}} + +You must specify the user's current password to use the `sensuctl user change-password` command. + +### Reset a user password + +To reset a user password without specifying the current password, run: + +{{< code shell >}} +sensuctl user reset-password --interactive +{{< /code >}} + +You must have admin permissions to use the `sensuctl user reset-password` command. + +### Test a user password + +To test the password for a user created with Sensu's built-in [basic authentication][11]: + +{{< code shell >}} +sensuctl user test-creds --password 'password' +{{< /code >}} + +An empty response indicates valid credentials. +A `request-unauthorized` response indicates invalid credentials. + +{{% notice note %}} +**NOTE**: The `sensuctl user test-creds` command tests passwords for users created with Sensu's built-in [basic authentication](../operations/control-access/#use-built-in-basic-authentication). +It does not test user credentials defined via an authentication provider like [Lightweight Directory Access Protocol (LDAP)](../operations/control-access/ldap-auth/), [Active Directory (AD)](../operations/control-access/ad-auth/), or [OpenID Connect 1.0 protocol (OIDC)](../operations/control-access/oidc-auth/). +{{% /notice %}} + +For example, if you test LDAP credentials with the `sensuctl user test-creds` command, the backend will log an error, even if the LDAP credentials are correct: + +{{< code text >}} +{"component":"apid.routers","error":"basic provider is disabled","level":"info","msg":"invalid username and/or password","time":"2020-02-07T20:42:14Z","user":"dev"} +{{< /code >}} + +### Generate a password hash + +You can use a password hash instead of a user's password in the sensuctl commands to [create][5] and [edit][13] users. +The `sensuctl user hash-password` command creates a [bcrypt hash][15] of the specified password. + +To generate a password hash for a specified cleartext password, run: + +{{< code shell >}} +sensuctl user hash-password +{{< /code >}} + +## Sensu backend URL + +The Sensu backend URL is the HTTP or HTTPS URL where sensuctl can connect to the Sensu backend server. +The default URL is `http://127.0.0.1:8080`. + +To connect to a [Sensu cluster][4], connect sensuctl to any single backend in the cluster. +For information about configuring the Sensu backend URL, read the [backend reference][3]. + +## Preferred output format + +After you [configure sensuctl][12], you can change the default output format for sensuctl responses. +Sensuctl supports the following output formats: + +Format | Description +------ | ----------- +`tabular` | Output is organized in user-friendly columns. Tabular is the default output format. +`yaml` | Output is in [YAML][20] format. Resource definitions include the resource `type` and `api_version` as well as an outer-level `spec` "wrapping" for the resource attributes. +`wrapped-json` | Output is in [JSON][21] format. Resource definitions include the resource `type` and `api_version` as well as an outer-level `spec` "wrapping" for the resource attributes. +`json` | Output is in [JSON][21] format. Resource definitions **do not** include the resource `type` and `api_version` or an outer-level `spec` "wrapping". + +Use `sensuctl config set-format` to [change the preferred output format][28]. + +### Output format significance + +To use [sensuctl create][5] to create a resource, you must provide the resource definition in `yaml` or `wrapped-json` format. +These formats include the resource `type`, which sensuctl needs to determine what kind of resource to create. + +The [Sensu API][9] uses `json` output format for responses for APIs in the `core` [group][22]. +For APIs that are not in the `core` group, responses are in the `wrapped-json` output format. + +Sensu sends events to the backend in [`json` format][21], without the `spec` attribute wrapper or `type` and `api_version` attributes. + +## Sensuctl configuration files + +During configuration, sensuctl creates configuration files that contain information for connecting to your Sensu Go deployment. +You can find these files at `$HOME/.config/sensu/sensuctl/profile` and `$HOME/.config/sensu/sensuctl/cluster`. + +Use the `cat` command to view the contents of the configuration files. +For example, to view your sensuctl profile configuration, run: + +{{< code shell >}} +cat .config/sensu/sensuctl/profile +{{< /code >}} + +The response should be similar to this example: + +{{< code text >}} +{ + "format": "tabular", + "namespace": "default", + "username": "admin" +} +{{< /code >}} + +To view your sensuctl cluster configuration, run: + +{{< code shell >}} +cat .config/sensu/sensuctl/cluster +{{< /code >}} + +The response should be similar to this example: + +{{< code text >}} +{ + "api-url": "http://localhost:8080", + "trusted-ca-file": "", + "insecure-skip-tls-verify": false, + "access_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", + "expires_at": 1550082282, + "refresh_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" +} +{{< /code >}} + +The sensuctl configuration files are useful if you want to know which cluster you're connecting to or which namespace or username you're currently configured to use. + +## Get help for sensuctl commands + +Sensuctl supports a `--help` flag for each command and subcommand. +The help response includes a usage template and lists of any available flags and further commands and subcommands. + +To list global and command-specific flags for sensuctl in general, run: + +{{< code shell >}} +sensuctl --help +{{< /code >}} + +To list available flags and subcommands for a sensuctl command like `sensuctl check` or `sensuctl create`, run: + +{{< code shell >}} +sensuctl check --help +{{< /code >}} + +{{< code shell >}} +sensuctl create --help +{{< /code >}} + +To list available flags for a complete sensuctl command like `sensuctl check delete`, run: + +{{< code shell >}} +sensuctl check delete --help +{{< /code >}} + +## Manage sensuctl + +Use the `sencutl config` command to view and modify the current sensuctl configuration. + +To view flags and command options, run: + +{{< code shell >}} +sensuctl config --help +{{< /code >}} + +The response lists the global flags and commands available to use with `sensuctl config`: + +{{< code text >}} +Modify sensuctl configuration + +Usage: sensuctl config COMMAND + +Flags: + -h, --help help for config + +Global Flags: + --api-key string API key to use for authentication + --api-url string host URL of Sensu installation + --cache-dir string path to directory containing cache & temporary files (default "/home/vagrant/.cache/sensu/sensuctl") + --config-dir string path to directory containing configuration files (default "/home/vagrant/.config/sensu/sensuctl") + --insecure-skip-tls-verify skip TLS certificate verification (not recommended!) + --namespace string namespace in which we perform actions (default "default") + --timeout duration timeout when communicating with sensu backend (default 15s) + --trusted-ca-file string TLS CA certificate bundle in PEM format + +Commands: + set-format Set format for active profile + set-namespace Set namespace for active profile + set-timeout Set timeout for active profile in duration format (ex: 15s) + view Display active configuration +{{< /code >}} + +There are also commands for [logging out of sensuctl][29] and [viewing the current sensuctl version][30]. + +### View sensuctl config + +To view the active configuration for sensuctl: + +{{< code shell >}} +sensuctl config view +{{< /code >}} + +The `sensuctl config view` response includes the [Sensu backend URL][6], default [namespace][8] for the current user, default [output format][7] for the current user, and currently configured username: + +{{< code text >}} +=== Active Configuration +API URL: http://127.0.0.1:8080 +Namespace: default +Format: tabular +Username: admin +{{< /code >}} + +### Set preferred output format + +Use the `set-format` command to change the [preferred output format][7] for the current user. + +For example, to change the default tabular format to YAML for all sensuctl commands, run: + +{{< code shell >}} +sensuctl config set-format yaml +{{< /code >}} + +You can also use the `--format` flag to set the output format for the response to a single sensuctl command. +For example, to keep the default format set at tabular, but retrieve a specific entity definition in YAML format, run: + +{{< code shell >}} +sensuctl entity info --format yaml +{{< /code >}} + +### Set namespace + +Use the `set-namespace` command to change the default [namespace][8] for the current user. +For more information about configuring Sensu access control, read the [RBAC reference][1]. + +For example, to change the default namespace to `development`: + +{{< code shell >}} +sensuctl config set-namespace development +{{< /code >}} + +### Log out of sensuctl + +To log out of sensuctl: + +{{< code shell >}} +sensuctl logout +{{< /code >}} + +To log back in to sensuctl: + +{{< code shell >}} +sensuctl configure +{{< /code >}} + +### View the sensuctl version number + +To display the current version of sensuctl: + +{{< code shell >}} +sensuctl version +{{< /code >}} + +### Use global flags for sensuctl settings + +Global flags modify settings specific to sensuctl, such as the Sensu backend URL and [namespace][8]. + +{{< code text >}} +--api-key string API key to use for authentication +--api-url string host URL of Sensu installation +--cache-dir string path to directory containing cache & temporary files (default "/home/vagrant/.cache/sensu/sensuctl") +--config-dir string path to directory containing configuration files (default "/home/vagrant/.config/sensu/sensuctl") +--insecure-skip-tls-verify skip TLS certificate verification (not recommended!) +--namespace string namespace in which we perform actions (default "default") +--timeout duration timeout when communicating with sensu backend (default 15s) +--trusted-ca-file string TLS CA certificate bundle in PEM format +{{< /code >}} + +You can use global flags with most sensuctl commands. +To set global flags permanently, edit `.config/sensu/sensuctl/{cluster, profile}`. + +## Use shell autocompletion with sensuctl + +Use shell autocompletion to create and run valid sensuctl commands. +After you [install and configure autocompletion][25], you can use the **tab** key to view and select from available options for each part of a sensuctl command directly from the command line. + +Type `sensuctl` and press **tab** to view the list of available variables: + +{{< code text >}} +api-key cluster-role configure edit handler logout role user +asset cluster-role-binding create entity help mutator role-binding version +auth command delete env hook namespace secret +check completion describe-type event license pipeline silenced +cluster config dump filter login prune tessen +{{< /code >}} + +Type your selected variable and press **tab** again to view the list of available variables to complete the command: + +{{< code text >}} +create delete info list +{{< /code >}} + +Type your selected variable to complete the command and press **enter** to run it. + +### Install and configure autocompletion for sensuctl + +Follow the instructions in this section to install and configure Bash or zsh autocompletion for sensuctl. + +#### Install and configure for Bash + +To install and configure Bash autocompletion for sensuctl: + +1. Install [bash-completion][24]. + + {{% notice note %}} + **NOTE**: If you use a current version of Linux in a non-minimal installation, bash-completion may already be installed. + {{% /notice %}} + + To install bash-completion on macOS, run: +{{< code shell >}} +brew install bash-completion +{{< /code >}} + + Open `~/.bash_profile`, add the following lines, and save: +{{< code shell >}} +if [ -f $(brew --prefix)/etc/bash_completion ]; then +. $(brew --prefix)/etc/bash_completion +fi +{{< /code >}} + +2. Open `~/.bash_profile`, add the following line, and save: + + {{< code shell >}} +source <(sensuctl completion bash) +{{< /code >}} + +3. Run the following command to source your `~/.bash_profile` file so that its resources are available: + + {{< code shell >}} +source ~/.bash_profile +{{< /code >}} + +Shell autocompletion should now be available for sensuctl. + +#### Install and configure for zsh + +To install and configure zsh autocompletion for sensuctl: + +1. Open `~/.zshrc`, add the following line, and save: + + {{< code shell >}} +source <(sensuctl completion zsh) +{{< /code >}} + +2. Run the following command to source your `~/.zshrc` file so that its resources are available: + + {{< code shell >}} +source ~/.zshrc +{{< /code >}} + + +[1]: ../operations/control-access/rbac/ +[2]: ../operations/deploy-sensu/install-sensu/#install-sensuctl +[3]: ../observability-pipeline/observe-schedule/backend/ +[4]: ../operations/deploy-sensu/cluster-sensu/ +[5]: create-manage-resources/#create-resources +[6]: #sensu-backend-url +[7]: #preferred-output-format +[8]: #username-password-and-namespace +[9]: ../api/ +[10]: ../operations/deploy-sensu/install-sensu/#install-the-sensu-backend +[11]: ../operations/control-access/#use-built-in-basic-authentication +[12]: #first-time-setup-and-authentication +[13]: create-manage-resources/#update-resources +[14]: ../api/other/auth/ +[15]: https://en.wikipedia.org/wiki/Bcrypt +[16]: https://tools.ietf.org/html/rfc7519 +[17]: ../operations/control-access/ldap-auth +[18]: ../operations/control-access/ad-auth +[19]: ../commercial/ +[20]: https://yaml.org/ +[21]: https://www.json.org/ +[22]: ../api/core/ +[23]: ../observability-pipeline/observe-events/events/#example-status-only-event-from-the-sensu-api +[24]: https://github.com/scop/bash-completion +[25]: #install-and-configure-autocompletion-for-sensuctl +[26]: #usernamepassword-authentication +[27]: ../operations/control-access/namespaces/ +[28]: #set-preferred-output-format +[29]: #log-out-of-sensuctl +[30]: #view-the-sensuctl-version-number diff --git a/content/sensu-go/6.12/sensuctl/back-up-recover.md b/content/sensu-go/6.12/sensuctl/back-up-recover.md new file mode 100644 index 0000000000..0255061b42 --- /dev/null +++ b/content/sensu-go/6.12/sensuctl/back-up-recover.md @@ -0,0 +1,388 @@ +--- +title: "Back up and recover resources with sensuctl" +linkTitle: "Back Up and Recover Resources" +description: "Use sensuctl dump commands to export, back up, and recover some or all of your Sensu resources in YAML and JSON formats." +weight: 20 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: sensuctl +--- + +{{% notice protip %}} +**PRO TIP**: For disaster recovery instructions, read [Restore your Sensu configuration for disaster recovery](../../operations/maintain-sensu/disaster-recovery/). +{{% /notice %}} + +The sensuctl dump command allows you to export your [resources][6] to standard out (stdout) or to a file. +You can export all resources or a subset of them based on a list of resource types. +The dump command supports exporting in `wrapped-json` and `yaml`. + +For example, to export all resources for the current namespace to a file named `my-resources.yml` or `my-resources.json` in `yaml` or `wrapped-json` format: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl dump all --format yaml --file my-resources.yml +{{< /code >}} + +{{< code shell "Wrapped JSON" >}} +sensuctl dump all --format wrapped-json --file my-resources.json +{{< /code >}} + +{{< /language-toggle >}} + +You can [restore][3] exported resources with [sensuctl create][1]. + +{{% notice note %}} +**NOTE**: The sensuctl dump command does not export user passwords — you must add the [`password_hash`](../#generate-a-password-hash) or `password` attribute to any exported users resources before restoring them with sensuctl create.

    +In addition, sensuctl create does not restore API keys from a sensuctl dump backup, although you can use your backup as a reference for granting new API keys.

    +Because users and API keys require these additional steps to restore with sensuctl create, you might prefer to use the [etcd snapshot and restore process](https://etcd.io/docs/latest/op-guide/recovery/) as your primary backup and restore method. +Take regular etcd snapshots and make regular sensuctl dump backups for extra reassurance. +{{% /notice %}} + +## Back up before a Sensu version upgrade + +You should create a backup before you [upgrade][4] to a new version of Sensu. +Here's the step-by-step process: + +1. Create a backup folder. +{{< code shell >}} +mkdir backup +{{< /code >}} + +2. Create a backup of the entire cluster, except entities, events, and [role-based access control (RBAC)][2] resources, for all namespaces. +{{< language-toggle >}} +{{< code shell "YML" >}} +sensuctl dump all \ +--all-namespaces \ +--omit core/v2.Entity,core/v2.Event,core/v2.APIKey,core/v2.User,core/v2.Role,core/v2.RoleBinding,core/v2.ClusterRole,core/v2.ClusterRoleBinding \ +--format yaml \ +--file backup/config.yml +{{< /code >}} +{{< code shell "Wrapped JSON" >}} +sensuctl dump all \ +--all-namespaces \ +--omit core/v2.Entity,core/v2.Event,core/v2.APIKey,core/v2.User,core/v2.Role,core/v2.RoleBinding,core/v2.ClusterRole,core/v2.ClusterRoleBinding \ +--format wrapped-json \ +--file backup/config.json +{{< /code >}} +{{< /language-toggle >}} + +3. Export your [RBAC][2] resources, except API keys and users, for all namespaces. +{{< language-toggle >}} +{{< code shell "YML" >}} +sensuctl dump core/v2.Role,core/v2.RoleBinding,core/v2.ClusterRole,core/v2.ClusterRoleBinding \ +--all-namespaces \ +--format yaml \ +--file backup/rbac.yml +{{< /code >}} +{{< code shell "Wrapped JSON" >}} +sensuctl dump core/v2.Role,core/v2.RoleBinding,core/v2.ClusterRole,core/v2.ClusterRoleBinding \ +--all-namespaces \ +--format wrapped-json \ +--file backup/rbac.json +{{< /code >}} +{{< /language-toggle >}} + +4. Export your API keys and users resources for all namespaces. +{{< language-toggle >}} +{{< code shell "YML" >}} +sensuctl dump core/v2.APIKey,core/v2.User \ +--all-namespaces \ +--format yaml \ +--file backup/cannotrestore.yml +{{< /code >}} +{{< code shell "Wrapped JSON" >}} +sensuctl dump core/v2.APIKey,core/v2.User \ +--all-namespaces \ +--format wrapped-json \ +--file backup/cannotrestore.json +{{< /code >}} +{{< /language-toggle >}} +{{% notice note %}} +**NOTE**: Passwords are not included when you export users. +You must add the [`password_hash`](../#generate-a-password-hash) or `password` attribute to any exported `users` resources before you can use them with `sensuctl create`.

    +Because users require this additional configuration and API keys cannot be restored from a sensuctl dump backup, consider exporting your API keys and users to a different folder than `backup`. +{{% /notice %}} + +5. Export your entity resources for all namespaces (if desired). +{{< language-toggle >}} +{{< code shell "YML" >}} +sensuctl dump core/v2.Entity \ +--all-namespaces \ +--format yaml \ +--file backup/inventory.yml +{{< /code >}} +{{< code shell "Wrapped JSON" >}} +sensuctl dump core/v2.Entity \ +--all-namespaces \ +--format wrapped-json \ +--file backup/inventory.json +{{< /code >}} +{{< /language-toggle >}} +{{% notice note %}} +**NOTE**: If you do not export your entities, proxy check requests will not be scheduled for the excluded proxy entities. +{{% /notice %}} + +## Back up to populate new namespaces + +You can create a backup copy of your existing resources with their namespaces stripped from the record. +This backup allows you to [replicate resources across namespaces][5] without manual editing. + +To create a backup of your resources that you can replicate in new namespaces: + +1. Create a backup folder. +{{< code shell >}} +mkdir backup +{{< /code >}} + +2. Back up your pipeline resources for all namespaces, stripping namespaces so that your resources are portable for reuse in any namespace. +{{< language-toggle >}} +{{< code shell "YML" >}} +sensuctl dump core/v2.Asset,core/v2.CheckConfig,core/v2.HookConfig,core/v2.EventFilter,core/v2.Mutator,core/v2.Handler,core/v2.Silenced,secrets/v1.Secret,secrets/v1.Provider \ +--all-namespaces \ +--format yaml | grep -v "^\s*namespace:" > backup/pipelines.yml +{{< /code >}} +{{< code shell "Wrapped JSON" >}} +sensuctl dump core/v2.Asset,core/v2.CheckConfig,core/v2.HookConfig,core/v2.EventFilter,core/v2.Mutator,core/v2.Handler,core/v2.Silenced,secrets/v1.Secret,secrets/v1.Provider \ +--all-namespaces \ +--format wrapped-json | grep -v "^\s*namespace:" > backup/pipelines.json +{{< /code >}} +{{< /language-toggle >}} + +## Restore resources from backup + +When you are ready to restore your exported resources, use [`sensuctl create`][1]. + +To restore everything you exported all at once, run: + +{{< code shell >}} +sensuctl create -r -f backup/ +{{< /code >}} + +To restore a subset of your exported resources (in this example, your RBAC resources), run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl create -f backup/rbac.yml +{{< /code >}} + +{{< code shell "Wrapped JSON" >}} +sensuctl create -f backup/rbac.json +{{< /code >}} + +{{< /language-toggle >}} + +{{% notice note %}} +**NOTE**: When you export users, required password attributes are not included. +You must add a [`password_hash`](../#generate-a-password-hash) or `password` to `users` resources before restoring them with the `sensuctl create` command.

    +You can't restore API keys or users from a sensuctl dump backup. +API keys must be reissued, but you can use your backup as a reference for granting new API keys to replace the exported keys. +{{% /notice %}} + +## Supported resource types + +Use `sensuctl describe-type all` to retrieve the list of supported sensuctl dump resource types. + +{{% notice note %}} +**NOTE**: Short names are only supported for core/v2 resources. +{{% /notice %}} + +{{< code shell >}} +sensuctl describe-type all +{{< /code >}} + +The response will list the names and other details for the supported resource types: + +{{< code text >}} + Fully Qualified Name Short Name API Version Type Namespaced +────────────────────────────────────── ───────────────────── ─────────────────── ───────────────────────── ───────────── + authentication/v2.Provider authentication/v2 Provider false + licensing/v2.LicenseFile licensing/v2 LicenseFile false + store/v1.PostgresConfig store/v1 PostgresConfig false + federation/v1.EtcdReplicator federation/v1 EtcdReplicator false + federation/v1.Cluster federation/v1 Cluster false + secrets/v1.Secret secrets/v1 Secret true + secrets/v1.Provider secrets/v1 Provider false + searches/v1.Search searches/v1 Search true + web/v1.GlobalConfig web/v1 GlobalConfig false + bsm/v1.RuleTemplate bsm/v1 RuleTemplate true + bsm/v1.ServiceComponent bsm/v1 ServiceComponent true + pipeline/v1.SumoLogicMetricsHandler pipeline/v1 SumoLogicMetricsHandler true + pipeline/v1.TCPStreamHandler pipeline/v1 TCPStreamHandler true + core/v2.Namespace namespaces core/v2 Namespace false + core/v2.ClusterRole clusterroles core/v2 ClusterRole false + core/v2.ClusterRoleBinding clusterrolebindings core/v2 ClusterRoleBinding false + core/v2.User users core/v2 User false + core/v2.APIKey apikeys core/v2 APIKey false + core/v2.TessenConfig tessen core/v2 TessenConfig false + core/v2.Asset assets core/v2 Asset true + core/v2.CheckConfig checks core/v2 CheckConfig true + core/v2.Entity entities core/v2 Entity true + core/v2.Event events core/v2 Event true + core/v2.EventFilter filters core/v2 EventFilter true + core/v2.Handler handlers core/v2 Handler true + core/v2.HookConfig hooks core/v2 HookConfig true + core/v2.Mutator mutators core/v2 Mutator true + core/v2.Pipeline pipelines core/v2 Pipeline true + core/v2.Role roles core/v2 Role true + core/v2.RoleBinding rolebindings core/v2 RoleBinding true + core/v2.Silenced silenced core/v2 Silenced true +{{< /code >}} + +You can also list specific resource types by fully qualified name or short name: + +{{< code shell >}} +sensuctl describe-type core/v2.CheckConfig +{{< /code >}} + +{{< code shell >}} +sensuctl describe-type checks +{{< /code >}} + +To list more than one type, use a comma-separated list: + +{{< code shell >}} +sensuctl describe-type core/v2.CheckConfig,core/v2.EventFilter,core/v2.Handler +{{< /code >}} + +{{< code shell >}} +sensuctl describe-type checks,filters,handlers +{{< /code >}} + +### Format the sensuctl describe-type response + +Add the `--format` flag to specify how the resources should be formatted in the `sensuctl describe-type` response. +The default is unformatted, but you can specify either `wrapped-json` or `yaml`: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl describe-type core/v2.CheckConfig --format yaml +{{< /code >}} + +{{< code shell "Wrapped JSON">}} +sensuctl describe-type core/v2.CheckConfig --format wrapped-json +{{< /code >}} + +{{< /language-toggle >}} + +## Example sensuctl dump commands + +To export only checks for only the current namespace to stdout in YAML or wrapped JSON format: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl dump core/v2.CheckConfig --format yaml +{{< /code >}} + +{{< code shell "Wrapped JSON" >}} +sensuctl dump core/v2.CheckConfig --format wrapped-json +{{< /code >}} + +{{< /language-toggle >}} + +To export only handlers and filters for only the current namespace to a file named `my-handlers-and-filters` in YAML or wrapped JSON format: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl dump core/v2.Handler,core/v2.EventFilter --format yaml --file my-handlers-and-filters.yml +{{< /code >}} + +{{< code shell "Wrapped JSON" >}} +sensuctl dump core/v2.Handler,core/v2.EventFilter --format wrapped-json --file my-handlers-and-filters.json +{{< /code >}} + +{{< /language-toggle >}} + +To export resources for **all namespaces**, add the `--all-namespaces` flag to any sensuctl dump command. +For example: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl dump all --all-namespaces --format yaml --file my-resources.yml +{{< /code >}} + +{{< code shell "Wrapped JSON" >}} +sensuctl dump all --all-namespaces --format wrapped-json --file my-resources.json +{{< /code >}} + +{{< /language-toggle >}} + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl dump core/v2.CheckConfig --all-namespaces --format yaml +{{< /code >}} + +{{< code shell "Wrapped JSON" >}} +sensuctl dump core/v2.CheckConfig --all-namespaces --format wrapped-json +{{< /code >}} + +{{< /language-toggle >}} + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl dump core/v2.Handler,core/v2.EventFilter --all-namespaces --format yaml --file my-handlers-and-filters.yml +{{< /code >}} + +{{< code shell "Wrapped JSON" >}} +sensuctl dump core/v2.Handler,core/v2.EventFilter --all-namespaces --format wrapped-json --file my-handlers-and-filters.json +{{< /code >}} + +{{< /language-toggle >}} + +You can use [fully qualified names or short names][6] to specify resources in sensuctl dump commands. +Here's an example that uses fully qualified names: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl dump core/v2.Handler,core/v2.EventFilter --format yaml --file my-handlers-and-filters.yml +{{< /code >}} + +{{< code shell "Wrapped JSON" >}} +sensuctl dump core/v2.Handler,core/v2.EventFilter --format wrapped-json --file my-handlers-and-filters.json +{{< /code >}} + +{{< /language-toggle >}} + +Here's an example that uses short names: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl dump handlers,filters --format yaml --file my-handlers-and-filters.yml +{{< /code >}} + +{{< code shell "Wrapped JSON" >}} +sensuctl dump handlers,filters --format wrapped-json --file my-handlers-and-filters.json +{{< /code >}} + +{{< /language-toggle >}} + +## Best practices for sensuctl dump + +To reduce the running time for the sensuctl dump command, omit events and export only one namespace at a time. + +Omit events from your sensuctl dump command to reduce the size of the exported payload and the system resources required to export. +The most important part of a backup is capturing the Sensu configuration, and even with regular backups, events are likely to be outdated by the time you restore them. +If you need access to all events, send them to a database store instead of including events in routine Sensu backups. + +It takes longer to export resources from all namespaces at once than the resources from one namespace, especially as the number of resources in each namespace grows. +To export resources more quickly, export a single namespace at a time. + + +[1]: ../create-manage-resources/#create-resources +[2]: ../../operations/control-access/rbac/ +[3]: #restore-resources-from-backup +[4]: ../../operations/maintain-sensu/upgrade/ +[5]: ../create-manage-resources/#create-resources-across-namespaces +[6]: #supported-resource-types diff --git a/content/sensu-go/6.12/sensuctl/create-manage-resources.md b/content/sensu-go/6.12/sensuctl/create-manage-resources.md new file mode 100644 index 0000000000..0da35b1fc4 --- /dev/null +++ b/content/sensu-go/6.12/sensuctl/create-manage-resources.md @@ -0,0 +1,1105 @@ +--- +title: "Create and manage resources with sensuctl" +linkTitle: "Create and Manage Resources" +description: "Use the sensuctl command line tool to create and manage resources within Sensu. Read this reference doc to learn how to use sensuctl." +weight: 10 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: sensuctl +--- + +Use the sensuctl command line tool to create and manage resources within Sensu. +Sensuctl works by calling Sensu’s underlying API to create, read, update, and delete resources, events, and entities. + +## Create resources + +The `sensuctl create` command allows you to create or update resources by reading from STDIN or a file. + +The `create` command accepts Sensu resource definitions in [`yaml` or `wrapped-json` formats][4], which wrap the contents of the resource in `spec` and identify the resource `type` and `api_version`. +Review the [list of supported resource types][3] `for sensuctl create`. +Read the [reference docs][6] for information about creating resource definitions. + +Resources that you create with `sensuctl create` will include the following label in the metadata: + +{{< language-toggle >}} + +{{< code yml >}} +sensu.io/managed_by: sensuctl +{{< /code >}} + +{{< code json >}} +{ + "sensu.io/managed_by": "sensuctl" +} +{{< /code >}} + +{{< /language-toggle >}} + +You can create more than one resource at a time with `sensuctl create`. +If you use YAML, separate the resource definitions by a line with three hyphens: `---`. +If you use wrapped JSON, separate the resources *without* a comma. + +{{% notice note %}} +**NOTE**: You can also use the `sensuctl create` command to create resources with sensuctl. +Read [Use the create subcommand](#use-the-create-subcommand) for more information and an example. +{{% /notice %}} + +### Create resources from STDIN + +The following example demonstrates how to use the EOF function with `sensuctl create` to create two resources by reading from STDIN: a `marketing-site` check and a `slack` handler. + +{{< language-toggle >}} + +{{< code shell "YML" >}} +cat << EOF | sensuctl create +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: marketing-site +spec: + command: http-check -u https://sensu.io + subscriptions: + - demo + interval: 15 + handlers: + - slack +--- +type: Handler +api_version: core/v2 +metadata: + name: slack +spec: + command: sensu-slack-handler --channel '#monitoring' + env_vars: + - SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX + type: pipe +EOF +{{< /code >}} + +{{< code shell "JSON" >}} +cat << EOF | sensuctl create +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata" : { + "name": "marketing-site" + }, + "spec": { + "command": "http-check -u https://sensu.io", + "subscriptions": ["demo"], + "interval": 15, + "handlers": ["slack"] + } +} +{ + "type": "Handler", + "api_version": "core/v2", + "metadata": { + "name": "slack" + }, + "spec": { + "command": "sensu-slack-handler --channel '#monitoring'", + "env_vars": [ + "SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX" + ], + "type": "pipe" + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + +### Create resources from a file + +The following example demonstrates how to use the `--file` flag with `sensuctl create` to create a `marketing-site` check and a `slack` handler. + +First, copy these resource definitions and save them in a file named `my-resources.yml` or `my-resources.json`: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: marketing-site +spec: + command: http-check -u https://sensu.io + subscriptions: + - demo + interval: 15 + handlers: + - slack +--- +type: Handler +api_version: core/v2 +metadata: + name: slack +spec: + command: sensu-slack-handler --channel '#monitoring' + env_vars: + - SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX + type: pipe +{{< /code >}} + +{{< code shell "JSON" >}} +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata" : { + "name": "marketing-site" + }, + "spec": { + "command": "http-check -u https://sensu.io", + "subscriptions": ["demo"], + "interval": 15, + "handlers": ["slack"] + } +} +{ + "type": "Handler", + "api_version": "core/v2", + "metadata": { + "name": "slack" + }, + "spec": { + "command": "sensu-slack-handler --channel '#monitoring'", + "env_vars": [ + "SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX" + ], + "type": "pipe" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +Run the following command to create the resources from `my-resources.yml` or `my-resources.json`: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl create --file my-resources.yml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl create --file my-resources.json +{{< /code >}} + +{{< /language-toggle >}} + +Or: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +cat my-resources.yml | sensuctl create +{{< /code >}} + +{{< code shell "JSON" >}} +cat my-resources.json | sensuctl create +{{< /code >}} + +{{< /language-toggle >}} + +### sensuctl create flags + +Run `sensuctl create -h` to view a usage example with command-specific and global flags: + +{{< code text >}} +Create or replace resources from file or URL (path, file://, http[s]://), or STDIN otherwise. + +Usage: sensuctl create [-r] [[-f URL] ... ] [flags] + +Flags: + -f, --file strings Files, directories, or URLs to create resources from + -h, --help help for create + -r, --recursive Follow subdirectories + +Global Flags: + --api-key string API key to use for authentication + --api-url string host URL of Sensu installation + --cache-dir string path to directory containing cache & temporary files (default "/home/vagrant/.cache/sensu/sensuctl") + --config-dir string path to directory containing configuration files (default "/home/vagrant/.config/sensu/sensuctl") + --insecure-skip-tls-verify skip TLS certificate verification (not recommended!) + --namespace string namespace in which we perform actions (default "default") + --timeout duration timeout when communicating with sensu backend (default 15s) + --trusted-ca-file string TLS CA certificate bundle in PEM format +{{< /code >}} + +### sensuctl create resource types + +Use sensuctl create with any of the following resource types: + +| sensuctl create types | | | +--------------------|---|---|--- +[`ad`][25] | `AdhocRequest` | [`Asset`][12] | [`CheckConfig`][13] +[`ClusterRole`][43] | [`ClusterRoleBinding`][45] | [`Entity`][14] | [`Env`][24] +[`EtcdReplicators`][29] | [`Event`][15] | [`EventFilter`][16] | [`GlobalConfig`][11] +[`Handler`][17] | [`HookConfig`][18] | [`ldap`][26] | [`Mutator`][19] +[`Namespace`][21] | [`oidc`][37] | [`PostgresConfig`][32] | [`Role`][35] +[`RoleBinding`][44] | [`Secret`][28] | [`Silenced`][20] | [`SumoLogicMetricsHandler`][40] +[`TCPStreamHandler`][41] | [`TessenConfig`][27] | [`User`][22] | [`VaultProvider`][24] + +### Create resources across namespaces + +If you omit the `namespace` attribute from resource definitions, you can use the `senusctl create --namespace` flag to specify the namespace for a group of resources at the time of creation. +This allows you to replicate resources across namespaces without manual editing. + +To learn more about namespaces, read the [namespaces reference][21]. +The RBAC reference includes a list of [namespaced resource types][38]. + +The `sensuctl create` command applies namespaces to resources in the following order, from highest precedence to lowest: + +1. **Namespace specified within resource definitions**: You can specify a resource's namespace within individual resource definitions using the `namespace` attribute. +Namespaces specified in resource definitions take precedence over all other methods. +2. **`--namespace` flag**: If resource definitions do not specify a namespace, Sensu applies the namespace provided by the `sensuctl create --namespace` flag. +3. **Current sensuctl namespace configuration**: If you do not specify an embedded `namespace` attribute or use the `--namespace` flag, Sensu applies the namespace configured in the current sensuctl session. +Read [Manage sensuctl][31] to view your current session config and set the session namespace. + +For example, this handler does not include a `namespace` attribute: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Handler +api_version: core/v2 +metadata: + name: pagerduty +spec: + command: sensu-pagerduty-handler + env_vars: + - PAGERDUTY_TOKEN=SECRET + type: pipe +{{< /code >}} + +{{< code json >}} +{ + "type": "Handler", + "api_version": "core/v2", + "metadata": { + "name": "pagerduty" + }, + "spec": { + "command": "sensu-pagerduty-handler", + "env_vars": [ + "PAGERDUTY_TOKEN=SECRET" + ], + "type": "pipe" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +If you save this resource definition in a file named `pagerduty.yml` or `pagerduty.json`, you can create the `pagerduty` handler in any namespace with specific sensuctl commands. + +To create the handler in the `default` namespace: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl create --file pagerduty.yml --namespace default +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl create --file pagerduty.json --namespace default +{{< /code >}} + +{{< /language-toggle >}} + +To create the `pagerduty` handler in the `production` namespace: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl create --file pagerduty.yml --namespace production +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl create --file pagerduty.json --namespace production +{{< /code >}} + +{{< /language-toggle >}} + +To create the `pagerduty` handler in the current session namespace: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl create --file pagerduty.yml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl create --file pagerduty.json +{{< /code >}} + +{{< /language-toggle >}} + +## Delete resources + +The `sensuctl delete` command allows you to delete resources by reading from STDIN or a file. + +You can use `sensuctl delete` with the same [resource types][3] as `sensuctl create`. + +The `delete` command accepts Sensu resource definitions in `wrapped-json` and `yaml` formats. +To be deleted successfully, the name and namespace of a resource provided to the `delete` command must match the name and namespace of an existing resource. + +### Delete resources with STDIN + +To delete the `marketing-site` check from the current namespace with STDIN, run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +cat << EOF | sensuctl delete +--- +type: CheckConfig +api_version: core/v2 +metadata: + name: marketing-site +spec: + command: http-check -u https://sensu.io + subscriptions: + - demo + interval: 15 + handlers: + - slack +EOF +{{< /code >}} + +{{< code shell "JSON" >}} +cat << EOF | sensuctl delete +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata" : { + "name": "marketing-site" + }, + "spec": { + "command": "http-check -u https://sensu.io", + "subscriptions": ["demo"], + "interval": 15, + "handlers": ["slack"] + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + +### Delete resources using a file + +To delete all resources listed in a specific file from Sensu (in this example, a file named `my-resources.yml` or `my-resources.json`): + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl delete --file my-resources.yml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl delete --file my-resources.json +{{< /code >}} + +{{< /language-toggle >}} + +Or: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +cat my-resources.yml | sensuctl delete +{{< /code >}} + +{{< code shell "JSON" >}} +cat my-resources.json | sensuctl delete +{{< /code >}} + +{{< /language-toggle >}} + +### sensuctl delete flags + +Run `sensuctl delete -h` to view a usage example with command-specific and global flags: + +{{< code text >}} +Delete resources from file or STDIN + +Usage: sensuctl delete [-f FILE] [flags] + +Flags: + -f, --file string File to delete resources from + -h, --help help for delete + +Global Flags: + --api-key string API key to use for authentication + --api-url string host URL of Sensu installation + --cache-dir string path to directory containing cache & temporary files (default "/home/vagrant/.cache/sensu/sensuctl") + --config-dir string path to directory containing configuration files (default "/home/vagrant/.config/sensu/sensuctl") + --insecure-skip-tls-verify skip TLS certificate verification (not recommended!) + --namespace string namespace in which we perform actions (default "default") + --timeout duration timeout when communicating with sensu backend (default 15s) + --trusted-ca-file string TLS CA certificate bundle in PEM format +{{< /code >}} + +### Delete resources across namespaces + +To use the `senusctl delete --namespace` flag to specify the namespace for a group of resources at the time of deletion, omit the `namespace` attribute from resource definitions. +This allows you to remove resources across namespaces without manual editing. + +For example, suppose you added the `pagerduty` handler from [Create resources across namespaces][33] in every namespace. +To delete the `pagerduty` handler from only the `production` namespace using STDIN, run: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +cat << EOF | sensuctl delete --namespace production +--- +type: Handler +api_version: core/v2 +metadata: + name: pagerduty +spec: + command: sensu-pagerduty-handler + env_vars: + - PAGERDUTY_TOKEN=SECRET + type: pipe +EOF +{{< /code >}} + +{{< code shell "JSON" >}} +cat << EOF | sensuctl delete --namespace production +{ + "type": "Handler", + "api_version": "core/v2", + "metadata": { + "name": "pagerduty" + }, + "spec": { + "command": "sensu-pagerduty-handler", + "env_vars": [ + "PAGERDUTY_TOKEN=SECRET" + ], + "type": "pipe" + } +} +EOF +{{< /code >}} + +{{< /language-toggle >}} + +You can also use the `sensuctl delete` command with a file that includes the `pagerduty` handler definition (in these examples, the file name is `pagerduty.yml` or `pagerduty.json`). + +Delete the `pagerduty` handler from the `default` namespace with this command: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl delete --file pagerduty.yml --namespace default +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl delete --file pagerduty.json --namespace default +{{< /code >}} + +{{< /language-toggle >}} + +To delete the `pagerduty` handler from the `production` namespace: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl delete --file pagerduty.yml --namespace production +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl delete --file pagerduty.json --namespace production +{{< /code >}} + +{{< /language-toggle >}} + +To delete the `pagerduty` handler in the current session namespace: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl delete --file pagerduty.yml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl delete --file pagerduty.json +{{< /code >}} + +{{< /language-toggle >}} + +## Update resources + +Sensuctl allows you to update resource definitions with a text editor. +To use `sensuctl edit`, specify the resource [type][5] and resource name. + +{{% notice note %}} +**NOTE**: You cannot use sensuctl to update [agent-managed entities](../../observability-pipeline/observe-entities/entities/#manage-agent-entities-via-the-agent). +Requests to update agent-managed entities via sensuctl will fail and return an error. +{{% /notice %}} + +For example, to edit a handler named `slack` with `sensuctl edit`: + +{{< code shell >}} +sensuctl edit handler slack +{{< /code >}} + +{{% notice note %}} +**NOTE**: You cannot use sensuctl to update [agent-managed entities](../../observability-pipeline/observe-entities/entities/#manage-agent-entities-via-the-agent). +Requests to update agent-managed entities via sensuctl will fail and return an error. +{{% /notice %}} + +### sensuctl edit flags + +Run `sensuctl edit -h` to view a usage example with command-specific and global flags: + +{{< code text >}} +Edit resources interactively + +Usage: sensuctl edit [RESOURCE TYPE] [KEY]... [flags] + +Flags: + -b, --blank edit a blank resource, and create it on save + --format string format of data returned ("json"|"wrapped-json"|"tabular"|"yaml") (default "tabular") + -h, --help help for edit + +Global Flags: + --api-key string API key to use for authentication + --api-url string host URL of Sensu installation + --cache-dir string path to directory containing cache & temporary files (default "/home/vagrant/.cache/sensu/sensuctl") + --config-dir string path to directory containing configuration files (default "/home/vagrant/.config/sensu/sensuctl") + --insecure-skip-tls-verify skip TLS certificate verification (not recommended!) + --namespace string namespace in which we perform actions (default "default") + --timeout duration timeout when communicating with sensu backend (default 15s) + --trusted-ca-file string TLS CA certificate bundle in PEM format +{{< /code >}} + +### sensuctl edit resource types + +Use the `sensuctl edit` command with any of the following resource types: + +| sensuctl edit types | | | +--------------------|---|---|--- +[`asset`][12] | [`auth`][39] | [`check`][13] | [`cluster`][7] +[`cluster-role`][43] | [`cluster-role-binding`][45] | [`entity`][14] | [`event`][15] +[`filter`][16] | [`handler`][17] | [`hook`][18] | [`mutator`][19] +[`namespace`][21] | [`pipeline`][9] | [`role`][35] | [`role-binding`][44] +[`silenced`][20] | [`user`][22] + +## Manage resources + +Sensuctl provides the commands listed below for managing individual Sensu resources. +Combine the resource command with a [subcommand][23] to complete operations like listing all checks or deleting a specific silence. + +- [`sensuctl asset`][12] +- [`sensuctl auth`][39] (commercial feature) +- [`sensuctl check`][13] +- [`sensuctl cluster`][7] +- [`sensuctl cluster-role`][43] +- [`sensuctl cluster-role-binding`][45] +- [`sensuctl entity`][14] +- [`sensuctl event`][15] +- [`sensuctl filter`][16] +- [`sensuctl handler`][17] +- [`sensuctl hook`][18] +- [`sensuctl license`][34] (commercial feature) +- [`sensuctl mutator`][19] +- [`sensuctl namespace`][21] +- [`sensuctl pipeline`][9] +- [`sensuctl role`][35] +- [`sensuctl role-binding`][44] +- [`sensuctl secret`][28] +- [`sensuctl silenced`][20] +- [`sensuctl tessen`][27] +- [`sensuctl user`][22] + +### Subcommands + +Sensuctl provides a set of operation subcommands for each resource type. + +To view the supported subcommands for a resource type, run the resource command followed by the help flag, `-h`. +For example, to view the subcommands for `sensuctl check`, run: + +{{< code shell >}} +sensuctl check -h +{{< /code >}} + +The response includes a usage example, the supported command-specific and global flags, and a list of supported subcommands. + +Many resource types include a standard set of list, info, and delete operation subcommands: + +{{< code text >}} +delete delete resource given resource name +info show detailed resource information given resource name +list list resources +{{< /code >}} + +{{% notice note %}} +**NOTE**: The delete, info, and list subcommands are not supported for all resource types. +Run `sensuctl -h` to confirm which subcommands are supported for a specific resource type. +You can also configure [shell completion for sensuctl](../#use-shell-autocompletion-with-sensuctl) to view available variables for sensuctl commands. +{{% /notice %}} + +Use the commands with their flags and subcommands to get more information about your resources. +For example, to list all monitoring checks: + +{{< code shell >}} +sensuctl check list +{{< /code >}} + +To list checks from all namespaces: + +{{< code shell >}} +sensuctl check list --all-namespaces +{{< /code >}} + +To write all checks to `my-resources.yml` in `yaml` format or to `my-resources.json` in `wrapped-json` format: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl check list --format yaml > my-resources.yml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl check list --format wrapped-json > my-resources.json +{{< /code >}} + +{{< /language-toggle >}} + +To view the definition for a check named `check-cpu`: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl check info check-cpu --format yaml +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl check info check-cpu --format wrapped-json +{{< /code >}} + +{{< /language-toggle >}} + +To delete the definition for a check named `check-cpu`: + +{{< code shell >}} +sensuctl check delete check-cpu +{{< /code >}} + +In addition to the delete, info, and list operations, many commands support flags and subcommands that allow you to take special action based on the resource type. +The sections below describe some of the resource-specific operations. + +Run `sensuctl -h` to retrieve a complete list of the supported flags and subcommands for a specific resource command. +You can also configure [shell completion for sensuctl][46] to view available variables for sensuctl commands. + +#### Use the create subcommand + +Many resource types include a `create` subcommand that you can use to create resources using flags. +Run `sensuctl create -h` to get a list of the supported flags for the resource type. + +For example, run this command to create a check, using flags to specify the check's command, interval, subscriptions, and runtime assets: + +{{< code shell >}} +sensuctl check create check_cpu \ +--command 'check-cpu-usage -w 75 -c 90' \ +--interval 60 \ +--subscriptions system \ +--runtime-assets sensu/check-cpu-usage +{{< /code >}} + +The command creates a check with the following definition: + +{{< language-toggle >}} + +{{< code yml >}} +type: CheckConfig +api_version: core/v2 +metadata: + created_by: admin + name: check_cpu + namespace: default +spec: + check_hooks: null + command: check-cpu-usage -w 75 -c 90 + env_vars: null + handlers: [] + high_flap_threshold: 0 + interval: 60 + low_flap_threshold: 0 + output_metric_format: "" + output_metric_handlers: null + pipelines: [] + proxy_entity_name: "" + publish: true + round_robin: false + runtime_assets: + - sensu/check-cpu-usage + secrets: null + stdin: false + subdue: null + subscriptions: + - system + timeout: 0 + ttl: 0 +{{< /code >}} + +{{< code json >}} +{ + "type": "CheckConfig", + "api_version": "core/v2", + "metadata": { + "created_by": "admin", + "name": "check_cpu", + "namespace": "default" + }, + "spec": { + "check_hooks": null, + "command": "check-cpu-usage -w 75 -c 90", + "env_vars": null, + "handlers": [], + "high_flap_threshold": 0, + "interval": 60, + "low_flap_threshold": 0, + "output_metric_format": "", + "output_metric_handlers": null, + "pipelines": [], + "proxy_entity_name": "", + "publish": true, + "round_robin": false, + "runtime_assets": [ + "sensu/check-cpu-usage" + ], + "secrets": null, + "stdin": false, + "subdue": null, + "subscriptions": [ + "system" + ], + "timeout": 0, + "ttl": 0 + } +} +{{< /code >}} + +{{< /language-toggle >}} + +{{% notice note %}} +**NOTE**: Resources created with the `sensuctl create` subcommand **do not** include the label `sensu.io/managed_by: sensuctl`. +{{% /notice %}} + +#### Handle large datasets + +When using sensuctl to retrieve large datasets with the `list` command, add the `--chunk-size` flag to prevent query timeouts and improve performance. +The `--chunk-size` flag allows you to specify how many events Sensu should retrieve with each query. +Sensu will make a series of queries to retrieve all resources instead of a single query. + +For example, the following command returns the same output as `sensuctl event list` but makes multiple API queries, each for the number of resources specified with `--chunk-size`, instead of one query for the complete dataset: + +{{< code shell >}} +sensuctl event list --chunk-size 500 +{{< /code >}} + +#### Execute a check on demand + +The `sensuctl check execute` command executes the specified check on demand: + +{{< code shell >}} +sensuctl check execute +{{< /code >}} + +For example, the following command executes the `check-cpu` check with an attached message: + +{{< code shell >}} +sensuctl check execute check-cpu --reason "giving a sensuctl demo" +{{< /code >}} + +You can also use the `--subscriptions` flag to override the subscriptions in the check definition: + +{{< code shell >}} +sensuctl check execute check-cpu --subscriptions demo,webserver +{{< /code >}} + +#### Manage a Sensu cluster + +The `sensuctl cluster` command lets you manage a Sensu cluster with the following subcommands: + +{{< code text >}} +health get sensu health status +id show sensu cluster id +member-add add cluster member to an existing cluster, with comma-separated peer addresses +member-list list cluster members +member-remove remove cluster member by ID +member-update update cluster member by ID with comma-separated peer addresses +{{< /code >}} + +To view cluster members: + +{{< code shell >}} +sensuctl cluster member-list +{{< /code >}} + +To review the health of your Sensu cluster: + +{{< code shell >}} +sensuctl cluster health +{{< /code >}} + +#### Manually resolve events + +Use `sensuctl event resolve` to manually resolve events: + +{{< code shell >}} +sensuctl event resolve +{{< /code >}} + +For example, the following command manually resolves an event created by the entity `webserver1` and the check `check-http`: + +{{< code shell >}} +sensuctl event resolve webserver1 check-http +{{< /code >}} + +#### Use the sensuctl namespace command + +The sensuctl namespace commands have a few special characteristics that you should be aware of. + +**sensuctl namespace create** + +Namespace names can contain alphanumeric characters and hyphens and must begin and end with an alphanumeric character. + +**senscutl namespace list** + +In the packaged Sensu Go distribution, `sensuctl namespace list` lists only the namespaces for which the current user has access. + +**sensuctl namespace delete** + +Namespaces must be empty before you can delete them. +If the response to `sensuctl namespace delete` is `Error: resource is invalid: namespace is not empty`, the namespace may still contain events or other resources. + +To remove all resources and events so that you can delete a namespace, run this command (replace `` with the namespace you want to empty): + +{{< code shell >}} +sensuctl dump entities,events,assets,checks,filters,handlers,secrets/v1.Secret --namespace | sensuctl delete +{{< /code >}} + +## Prune resources + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access sensuctl pruning in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../commercial/). +{{% /notice %}} + +The `sensuctl prune` subcommand allows you to delete resources that do not appear in a given set of Sensu objects (called a "configuration") from a from a file, URL, or stdin. +For example, you can use `sensuctl create` to to apply a new configuration, then use `sensuctl prune` to prune unneeded resources, resources that were created by a specific user or that include a specific label selector, and more. + +{{% notice note %}} +**NOTE**: `sensuctl prune` is an alpha feature and may include breaking changes.

    +`sensuctl prune` can only delete resources that have the label `sensu.io/managed_by: sensuctl`, which Sensu automatically adds to resources created with the `sensuctl create` command. +This means you can only use `sensuctl prune` to delete resources that were created with `sensuctl create`. +{{% /notice %}} + +The pruning operation always follows the role-based access control (RBAC) permissions of the current user. +For example, to prune resources in the `dev` namespace, the current user who sends the prune command must have delete access to the `dev` namespace. + +### Supported resource types + +To retrieve the supported `sensuctl prune` resource types, run: + +{{< code shell >}} +sensuctl describe-type all +{{< /code >}} + +The response will list all supported `sensuctl prune` resource types: + +{{< code text >}} + Fully Qualified Name Short Name API Version Type Namespaced +────────────────────────────────────── ───────────────────── ─────────────────── ───────────────────────── ───────────── + authentication/v2.Provider authentication/v2 Provider false + licensing/v2.LicenseFile licensing/v2 LicenseFile false + store/v1.PostgresConfig store/v1 PostgresConfig false + federation/v1.EtcdReplicator federation/v1 EtcdReplicator false + federation/v1.Cluster federation/v1 Cluster false + secrets/v1.Secret secrets/v1 Secret true + secrets/v1.Provider secrets/v1 Provider false + searches/v1.Search searches/v1 Search true + web/v1.GlobalConfig web/v1 GlobalConfig false + bsm/v1.RuleTemplate bsm/v1 RuleTemplate true + bsm/v1.ServiceComponent bsm/v1 ServiceComponent true + pipeline/v1.SumoLogicMetricsHandler pipeline/v1 SumoLogicMetricsHandler true + pipeline/v1.TCPStreamHandler pipeline/v1 TCPStreamHandler true + core/v2.Namespace namespaces core/v2 Namespace false + core/v2.ClusterRole clusterroles core/v2 ClusterRole false + core/v2.ClusterRoleBinding clusterrolebindings core/v2 ClusterRoleBinding false + core/v2.User users core/v2 User false + core/v2.APIKey apikeys core/v2 APIKey false + core/v2.TessenConfig tessen core/v2 TessenConfig false + core/v2.Asset assets core/v2 Asset true + core/v2.CheckConfig checks core/v2 CheckConfig true + core/v2.Entity entities core/v2 Entity true + core/v2.Event events core/v2 Event true + core/v2.EventFilter filters core/v2 EventFilter true + core/v2.Handler handlers core/v2 Handler true + core/v2.HookConfig hooks core/v2 HookConfig true + core/v2.Mutator mutators core/v2 Mutator true + core/v2.Pipeline pipelines core/v2 Pipeline true + core/v2.Role roles core/v2 Role true + core/v2.RoleBinding rolebindings core/v2 RoleBinding true + core/v2.Silenced silenced core/v2 Silenced true +{{< /code >}} + +{{% notice note %}} +**NOTE**: Short names are only supported for core/v2 resources. +{{% /notice %}} + +### sensuctl prune flags + +Run `sensuctl prune -h` to view command-specific and global flags. +The following table describes the command-specific flags. + +| Flag | Function and important notes +| ---- | ---------------------------- +`-a` or `--all-users` | Prunes resources created by all users. Mutually exclusive with the `--users` flag. Defaults to false. +`-c` or `--cluster-wide` | Prunes any cluster-wide (non-namespaced) resources that are not defined in the configuration. Defaults to false. +`-d` or `--dry-run` | Prints the resources that will be pruned but does not actually delete them. Defaults to false. +`-f` or `--file` | Files, URLs, or directories to prune resources from. Strings. +`-h` or `--help` | Help for the prune command. +`--label-selector` | Prunes only resources that match the specified labels (comma-separated strings). Labels are a [commercial feature][30]. +`-o` or `--omit` | Resources that should be excluded from being pruned. +`-r` or `--recursive` | Prune command will follow subdirectories. +`-u` or `--users` | Prunes only resources that were created by the specified users (comma-separated strings). Defaults to the currently configured sensuctl user. + +### sensuctl prune usage + +{{< code shell >}} +sensuctl prune ,... -f [-r] ... ] --namespace +{{< /code >}} + +In this example `sensuctl prune` command: + +- Replace `` with the [fully qualified name or short name][10] of the resource you want to prune. +You must specify at least one resource type or the `all` qualifier (to prune all resource types). +- Replace `` with the name of the file or the URL that contains the set of Sensu objects you want to keep (the configuration). +- Replace `` with the namespace where you want to apply pruning. + If you omit the namespace qualifier, the command defaults to the current configured namespace. +- Replace `` with the other flags you want to use, if any. + +Use a comma separator to prune more than one resource in a single command. +For example, to prune checks and dynamic runtime assets from the file `checks.yaml` or `checks.json` for the `dev` namespace and the `admin` and `ops` users: + +{{< language-toggle >}} + +{{< code shell "YML" >}} +sensuctl prune core/v2.CheckConfig,core/v2.Asset --file checks.yaml --namespace dev --users admin,ops +{{< /code >}} + +{{< code shell "JSON" >}} +sensuctl prune core/v2.CheckConfig,core/v2.Asset --file checks.json --namespace dev --users admin,ops +{{< /code >}} + +{{< /language-toggle >}} + +`sensuctl prune` supports pruning resources by their fully qualified names or short names: + +Fully qualified names: + +{{< code shell >}} +sensuctl prune core/v2.CheckConfig,core/v2.Entity +{{< /code >}} + +Short names: + +{{< code shell >}} +sensuctl prune checks,entities +{{< /code >}} + +Use the `all` qualifier to prune all supported resources: + +{{< code shell >}} +sensuctl prune all +{{< /code >}} + +Use the `--omit` flag to identify resources you want to exclude from being pruned: + +{{< code shell >}} +sensuctl prune all --omit core/v2.Role,core/v2.RoleBinding,core/v2.ClusterRole,core/v2.ClusterRoleBinding +{{< /code >}} + +## Time formats + +Sensuctl supports multiple formats for resource attributes that require a time. +To specify an exact point in time (for example, when setting a silence), use full dates with times. + +Although supported formats depend on the resource type, sensuctl generally supports the following formats for dates with time: + +* [RFC 3339][42] with numeric zone offset: `2018-05-10T07:04:00-08:00` or + `2018-05-10T15:04:00Z` +* [RFC 3339][42] with space delimiters and numeric zone offset: `2018-05-10 07:04:00 + -08:00` +* Sensu alpha legacy format with canonical zone ID: `May 10 2018 7:04AM + America/Vancouver` + +Use the `--help` (`-h`) flag for specific sensuctl commands and resources to learn which time format to use. + +Supported canonical time zone IDs are defined in the [tz database][2]. + +{{% notice warning %}} +**WARNING**: Windows does not support canonical zone IDs (for example, `America/Vancouver`). +{{% /notice %}} + + +[1]: ../../operations/control-access/rbac/ +[2]: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones +[3]: #sensuctl-create-resource-types +[4]: ../#preferred-output-format +[5]: #sensuctl-edit-resource-types +[6]: ../../reference/ +[7]: ../../operations/deploy-sensu/cluster-sensu/ +[8]: ../../operations/control-access/rbac/#user-specification +[9]: ../../observability-pipeline/observe-process/pipelines/ +[10]: #supported-resource-types +[11]: ../../web-ui/webconfig-reference/ +[12]: ../../plugins/assets/ +[13]: ../../observability-pipeline/observe-schedule/checks/ +[14]: ../../observability-pipeline/observe-entities/entities/ +[15]: ../../observability-pipeline/observe-events/events/ +[16]: ../../observability-pipeline/observe-filter/filters/ +[17]: ../../observability-pipeline/observe-process/handlers/ +[18]: ../../observability-pipeline/observe-schedule/hooks/ +[19]: ../../observability-pipeline/observe-transform/mutators/ +[20]: ../../observability-pipeline/observe-process/silencing/ +[21]: ../../operations/control-access/namespaces/ +[22]: ../../operations/control-access/rbac#users +[23]: #subcommands +[24]: ../../operations/manage-secrets/secrets-providers/ +[25]: ../../operations/control-access/ad-auth/ +[26]: ../../operations/control-access/ldap-auth/ +[27]: ../../operations/monitor-sensu/tessen/ +[28]: ../../operations/manage-secrets/secrets/ +[29]: ../../operations/deploy-sensu/etcdreplicators/ +[30]: ../../commercial/ +[31]: ../#manage-sensuctl +[32]: ../../operations/deploy-sensu/datastore/ +[33]: #create-resources-across-namespaces +[34]: ../../operations/maintain-sensu/license/ +[35]: ../../operations/control-access/rbac/#roles +[36]: #sensuctl-create-flags +[37]: ../../operations/control-access/oidc-auth/ +[38]: ../../operations/control-access/rbac/#namespaced-resource-types +[39]: ../../operations/control-access/sso/ +[40]: ../../observability-pipeline/observe-process/sumo-logic-metrics-handlers/ +[41]: ../../observability-pipeline/observe-process/tcp-stream-handlers/ +[42]: https://www.ietf.org/rfc/rfc3339.txt +[43]: ../../operations/control-access/rbac/#cluster-roles +[44]: ../../operations/control-access/rbac/#role-bindings +[45]: ../../operations/control-access/rbac/#cluster-role-bindings +[46]: ../#use-shell-autocompletion-with-sensuctl diff --git a/content/sensu-go/6.12/sensuctl/environment-variables.md b/content/sensu-go/6.12/sensuctl/environment-variables.md new file mode 100644 index 0000000000..2a091d29c7 --- /dev/null +++ b/content/sensu-go/6.12/sensuctl/environment-variables.md @@ -0,0 +1,145 @@ +--- +title: "Set environment variables with sensuctl" +linkTitle: "Set Environment Variables" +description: "Use sensuctl to set environment variables for a single command or for all sensuctl commands and export and set environment variables on your system." +weight: 40 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: sensuctl +--- + +Sensu allows you to set sensuctl environment variables for a [single sensuctl command][1] or with [sensuctl configure][2]. +You can also export and set environment variables on your system with [sensuctl env][3]. + +These environment variables are alternatives to configuration flags like the [sensuctl global flags][4] and [sensuctl configure flags][5]. + +Setting sensuctl options as environment variables instead of using flags offers the following advantages: + +- Use environment variables to avoid exposing sensitive information like your API key and other security credentials. +Sensitive information is visible when you use command-line configuration flags. +- Inject exported environment variables for sensuctl commands in an automation script, such as a container creation script. +- Configure different shells for individual Sensu instances with the desired sets of environment variables rather than running sensuctl configure every time you want to switch between instances. + +## Set environment variables for a single command + +Set certain environment variables for a single sensuctl command to temporarily override your current settings. + +For example, to quickly check the entities in the `production` namespace while you are currently in the `default` namespace, run: + +{{< code shell >}} +SENSU_NAMESPACE=production sensuctl entity list +{{< /code >}} + +**Single-command environment variables are not persistent.** +To continue the example, if you run `sensuctl entity list` again, the response will include entities for the `default` namespace (not `production`). + +These are the environment variables you can set for a single sensuctl command: + +{{< code text >}} +SENSU_API_KEY API key to use for authentication +SENSU_API_URL host URL of Sensu installation +SENSU_CACHE_DIR path to directory containing cache & temporary files +SENSU_CONFIG_DIR path to directory containing configuration files +SENSU_INSECURE_SKIP_TLS_VERIFY skip TLS certificate verification (Boolean value) +SENSU_NAMESPACE namespace in which to perform actions (default "default") +SENSU_TIMEOUT timeout when communicating with sensu backend (default 15s) +SENSU_TRUSTED_CA_FILE TLS CA certificate bundle in PEM format +{{< /code >}} + +## Set environment variables with sensuctl configure + +To set certain environment variables with `sensuctl configure`, define the environment variables in the same command. +For example: + +{{< code shell >}} +SENSU_OIDC=true SENSU_NON_INTERACTIVE=true SENSU_FORMAT=yaml SENSU_PORT=7999 SENSU_TIMEOUT=49s SENSU_URL=http://192.168.7.217:8080 sensuctl configure +{{< /code >}} + +Environment variables set with `sensuctl configure` **are** persistent. + +These are the environment variables you can set for sensuctl configure: + +{{< code text >}} +SENSU_FORMAT preferred output format (default "tabular") +SENSU_NON_INTERACTIVE do not administer interactive questionnaire +SENSU_OIDC use an OIDC provider for authentication (Boolean value) +SENSU_PASSWORD password +SENSU_PORT (used with SENSU_OIDC) port for local HTTP web server used for OAuth 2 callback during OIDC authentication (default 8000) +SENSU_URL the sensu backend url (default "http://localhost:8080") +SENSU_USERNAME username +{{< /code >}} + +## Export environment variables with sensuctl env + +Export your shell environment with sensuctl env to use the exported environment variables with cURL and other scripts. + +This example shows how to use sensuctl env to export environment variables and configure your shell: + +{{< language-toggle >}} + +{{< code bash >}} +export SENSU_API_URL="http://127.0.0.1:8080" +export SENSU_NAMESPACE="default" +export SENSU_FORMAT="tabular" +export SENSU_ACCESS_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.x.x" +export SENSU_ACCESS_TOKEN_EXPIRES_AT="1567716187" +export SENSU_REFRESH_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.x.x" +export SENSU_TRUSTED_CA_FILE="" +export SENSU_INSECURE_SKIP_TLS_VERIFY="true" +eval $(sensuctl env) +{{< /code >}} + +{{< code cmd >}} +SET SENSU_API_URL=http://127.0.0.1:8080 +SET SENSU_NAMESPACE=default +SET SENSU_FORMAT=tabular +SET SENSU_ACCESS_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.x.x +SET SENSU_ACCESS_TOKEN_EXPIRES_AT=1567716676 +SET SENSU_REFRESH_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.x.x +SET SENSU_TRUSTED_CA_FILE= +SET SENSU_INSECURE_SKIP_TLS_VERIFY=true +@FOR /f "tokens=*" %i IN ('sensuctl env --shell cmd') DO @%i +{{< /code >}} + +{{< code powershell >}} +$Env:SENSU_API_URL = "http://127.0.0.1:8080" +$Env:SENSU_NAMESPACE = "default" +$Env:SENSU_FORMAT = "tabular" +$Env:SENSU_ACCESS_TOKEN = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.x.x" +$Env:SENSU_ACCESS_TOKEN_EXPIRES_AT = "1567716738" +$Env:SENSU_REFRESH_TOKEN = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.x.x" +$Env:SENSU_TRUSTED_CA_FILE = "" +$Env:SENSU_INSECURE_SKIP_TLS_VERIFY = "true" +& sensuctl env --shell powershell | Invoke-Expression +{{< /code >}} + +{{< /language-toggle >}} + +{{% notice note %}} +**NOTE**: If you receive an `invalid credentials` error while using sensuctl env, run `eval $(sensuctl env)` to refresh your token. +{{% /notice %}} + +The `sensuctl env` command allows you to export the following environment variables: + +{{< code text >}} +SENSU_API_KEY API key to use for authentication +SENSU_API_URL URL of the Sensu backend API in sensuctl +SENSU_NAMESPACE Name of the current namespace in sensuctl +SENSU_FORMAT Set output format in sensuctl (for example, JSON, YAML, etc.) +SENSU_ACCESS_TOKEN Current API access token in sensuctl +SENSU_ACCESS_TOKEN_EXPIRES_AT Timestamp specifying when the current API access token expires +SENSU_REFRESH_TOKEN Refresh token used to obtain a new access token +SENSU_TIMEOUT timeout when communicating with sensu backend (default 15s) +SENSU_TRUSTED_CA_FILE Path to a trusted CA file if set in sensuctl +SENSU_INSECURE_SKIP_TLS_VERIFY Boolean value that can be set to skip TLS verification +{{< /code >}} + + +[1]: #set-environment-variables-for-a-single-command +[2]: #set-environment-variables-with-sensuctl-configure +[3]: #set-environment-variables-with-sensuctl-env +[4]: ../#use-global-flags-for-sensuctl-settings +[5]: ../#sensuctl-configure-flags diff --git a/content/sensu-go/6.12/sensuctl/filter-responses.md b/content/sensu-go/6.12/sensuctl/filter-responses.md new file mode 100644 index 0000000000..738e910083 --- /dev/null +++ b/content/sensu-go/6.12/sensuctl/filter-responses.md @@ -0,0 +1,124 @@ +--- +title: "Filter responses with sensuctl" +linkTitle: "Filter Responses" +description: "Sensuctl supports response filtering for all commands using the list verb. Read this reference doc to learn about filtering responses with sensuctl." +weight: 30 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: sensuctl +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access sensuctl response filtering in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../commercial/). +{{% /notice %}} + +Sensuctl supports response filtering for all [commands using the `list` verb][1]. +For information about response filtering methods and available label and field selectors, read [API response filtering][2]. + +## Sensuctl-specific syntax + +You can use the same methods, selectors, and examples for sensuctl response filtering as for [API response filtering][2], except you'll format your requests with the `--label-selector` and `--field-selector` flags instead of cURL. + +The standard sensuctl response filtering syntax is: + +{{< code shell >}} +sensuctl list -- '' +{{< /code >}} + +To create a sensuctl response filtering command: + +- Replace `` with the resource your filter is based on. +- Replace `` with either `label-selector` or `field-selector`, depending on which selector you want to use. +- Replace `` with the filter to apply. + +For example: + +{{< code shell >}} +sensuctl event list --field-selector 'linux notin event.entity.subscriptions' +{{< /code >}} + +Sensuctl response filtering commands will also work with a single equals sign between the selector flag and the filter statement: + +{{< code shell >}} +sensuctl event list --field-selector='linux notin event.entity.subscriptions' +{{< /code >}} + +The [examples][6] demonstrate how to construct sensuctl filter statements for different selectors and operators. + +## Filter operators + +Sensuctl response filtering supports two equality-based operators, two set-based operators, one substring matching operator, and one logical operator. + +| operator | description | example | +| --------- | ------------------ | ---------------------- | +| `==` | Equality | `check.publish == true` +| `!=` | Inequality | `check.namespace != "default"` +| `in` | Included in | `linux in check.subscriptions` +| `notin` | Not included in | `slack notin check.handlers` +| `matches` | Substring matching | `check.name matches "linux-"` +| `&&` | Logical AND | `check.publish == true && slack in check.handlers` + +For details about operators, read about the [API response filtering operators][5]. + +## Examples + +### Filter responses with label selectors + +Use the `--label-selector` flag to filter responses using custom labels. + +For example, to return entities with the `proxy_type` label set to `switch`: + +{{< code shell >}} +sensuctl entity list --label-selector 'proxy_type == switch' +{{< /code >}} + +### Filter responses with field selectors + +Use the `--field-selector` flag to filter responses using specific [resource attributes][3]. + +For example, to return entities with the `switches` subscription: + +{{< code shell >}} +sensuctl entity list --field-selector 'switches in entity.subscriptions' +{{< /code >}} + +To retrieve all events that equal a status of `2` (CRITICAL): + +{{< code shell >}} +sensuctl event list --field-selector 'event.check.status == "2"' +{{< /code >}} + +To retrieve all entities whose name includes the substring `webserver`: + +{{< code shell >}} +sensuctl entity list --field-selector 'entity.name matches "webserver"' +{{< /code >}} + +### Use the logical AND operator + +To use the logical AND operator (`&&`) to return checks that include a `linux` subscription in the `dev` namespace: + +{{< code shell >}} +sensuctl check list --field-selector 'linux in check.subscriptions && dev in check.namespace' +{{< /code >}} + +### Combine label and field selectors + +You can combine the `--label-selector` and `--field-selector` flags in a single command. + +For example, this command returns checks with the `region` label set to `us-west-1` that also use the `slack` handler: + +{{< code shell >}} +sensuctl check list --label-selector 'region == "us-west-1"' --field-selector 'slack in check.handlers' +{{< /code >}} + + +[1]: ../create-manage-resources/#subcommands +[2]: ../../api/#response-filtering +[3]: ../../api#field-selector +[5]: ../../api/#filter-operators +[6]: #examples diff --git a/content/sensu-go/6.12/sensuctl/sensuctl-bonsai.md b/content/sensu-go/6.12/sensuctl/sensuctl-bonsai.md new file mode 100644 index 0000000000..9aeeccacd3 --- /dev/null +++ b/content/sensu-go/6.12/sensuctl/sensuctl-bonsai.md @@ -0,0 +1,197 @@ +--- +title: "Use sensuctl with Bonsai" +linkTitle: "Use sensuctl with Bonsai" +description: "Use sensuctl with Bonsai, the Sensu asset hub, to install dynamic runtime asset definitions and check for outdated dynamic runtime assets." +weight: 50 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: sensuctl +--- + +Sensuctl supports installing dynamic runtime asset definitions directly from [Bonsai, the Sensu asset hub][1], and checking your Sensu backend for outdated dynamic runtime assets. +You can also use `sensuctl command` to install, execute, list, and delete commands from Bonsai or a URL. + +## Install dynamic runtime asset definitions + +To install a dynamic runtime asset definition directly from Bonsai, use `sensuctl asset add :`. +Replace `` with the complete name of the dynamic runtime asset from Bonsai. +An asset's complete name includes both the part before the forward slash (sometimes called the Bonsai namespace) and the part after the forward slash. + +{{< figure src="/images/go/sensuctl_bonsai/name_namespace_location_bonsai_asset.png" alt="Bonsai page for the Sensu InfluxDB handler showing the location of the asset namespace and name" link="/images/go/sensuctl_bonsai/name_namespace_location_bonsai_asset.png" target="_blank" >}} + +Replace `` with the asset version you want to install. +To automatically install the latest version of the plugin, you do not need to specify the version: `sensuctl asset add `. + +{{% notice note %}} +**NOTE**: Specify the asset version you want to install to maintain the stability of your observability infrastructure. +If you do not specify a version to install, Sensu automatically installs the latest version, which may include breaking changes. +{{% /notice %}} + +For example, to install version 3.7.0 of the [sensu/sensu-influxdb-handler][4] dynamic runtime asset: + +{{< code shell >}} +sensuctl asset add sensu/sensu-influxdb-handler:3.7.0 +{{< /code >}} + +The response should be similar to this example: + +{{< code text >}} +fetching bonsai asset: sensu/sensu-influxdb-handler:3.7.0 +added asset: sensu/sensu-influxdb-handler:3.7.0 + +You have successfully added the Sensu asset resource, but the asset will not get downloaded until +it's invoked by another Sensu resource (ex. check). To add this runtime asset to the appropriate +resource, populate the "runtime_assets" field with ["sensu/sensu-influxdb-handler"]. +{{< /code >}} + +You can also use the `--rename` flag to rename the dynamic runtime asset on install: + +{{< code shell >}} +sensuctl asset add sensu/sensu-influxdb-handler:3.7.0 --rename influxdb-handler +{{< /code >}} + +{{% notice note %}} +**NOTE**: Sensu does not download and install dynamic runtime asset builds onto the system until they are needed for command execution. +Read the [asset reference](../../plugins/assets#dynamic-runtime-asset-builds) for more information about dynamic runtime asset builds. +{{% /notice %}} + +## Check your Sensu backend for outdated dynamic runtime assets + +To check your Sensu backend for dynamic runtime assets that have newer versions available on Bonsai, use `sensuctl asset outdated`. +This will print a list of dynamic runtime assets installed in the backend whose version is older than the newest version available on Bonsai: + +{{< code shell >}} +sensuctl asset outdated +{{< /code >}} + +If outdated assets are installed on the backend, the response will be similar to this example: + +{{< code text >}} + Asset Name Bonsai Asset Current Version Latest Version +---------------------------- ---------------------------- --------------- -------------- +sensu/sensu-influxdb-handler sensu/sensu-influxdb-handler 3.6.1 3.7.0 +{{< /code >}} + +## Extend sensuctl with commands + +Use `sensuctl command` to install, execute, list, and delete commands from Bonsai or a URL. + +### Install commands + +To install a sensuctl command from Bonsai or a URL: + +{{< code shell >}} +sensuctl command install (: | --url --checksum ) +{{< /code >}} + +To install a command plugin, use the Bonsai asset name or specify a URL and SHA512 checksum. + +**To install a command using the Bonsai asset name**, replace `` with the complete name of the asset from Bonsai. +`:` is only required if you require a specific version or are pinning to a specific version. +If you do not specify a version, sensuctl will fetch the latest version from Bonsai. + +Replace `` with a unique name for the command. +For example, for the [Sensu EC2 Discovery Plugin][3], you might use the alias `sensu-ec2-discovery`. +`` is required. + +Replace `` with the flags you want to use. +Run `sensuctl command install -h` to view flags. +Flags are optional and apply only to the `install` command — they are not saved as part of the command you are installing. + +To install a command from the [Sensu EC2 Discovery Plugin][3] with no flags: + +{{< code shell >}} +sensuctl command install sensu-ec2-discovery portertech/sensu-ec2-discovery:0.3.0 +{{< /code >}} + +**To install a command from a URL**, replace `` with a command URL that points to a tarball (for example, https://path/to/asset.tar.gz). +Replace `` with the checksum you want to use. +Replace `` with a unique name for the command. + +Replace `` with the flags you want to use. +Run `sensuctl command install -h` to view flags. +Flags are optional and apply only to the `install` command — they are not saved as part of the command you are installing. + +For example, to install a command-test dynamic runtime asset via URL with no flags: + +{{< code shell >}} +sensuctl command install command-test --url https://github.com/amdprophet/command-test/releases/download/v0.0.4/command-test_0.0.4_darwin_amd64.tar.gz --checksum 8b15a170e091dab42256fe64ca7c4a050ed49a9dbfd6c8129c95506a8a9a91f2762ac1a6d24f4fc545430613fd45abc91d3e5d3605fcfffb270dcf01996caa7f +{{< /code >}} + +{{% notice note %}} +**NOTE**: Dynamic runtime asset definitions with multiple asset builds are only supported via Bonsai. +{{% /notice %}} + +### Execute commands + +To execute a sensuctl command plugin via its dynamic runtime asset's bin/entrypoint executable: + +{{< code shell >}} +sensuctl command exec +{{< /code >}} + +Replace `` with a unique name for the command. +For example, for the [Sensu EC2 Discovery Plugin][3], you might use the alias `sensu-ec2-discovery`. +`` is required. + +Replace `` with the globlal flags you want to use. +Run `sensuctl command exec -h` to view global flags. +To pass `` flags to the bin/entrypoint executable, make sure to specify them after a double dash surrounded by spaces. + +Replace `` with the flags you want to use. +Run `sensuctl command exec -h` to view flags. +Flags are optional and apply only to the `exec` command — they are not saved as part of the command you are executing. + +{{% notice note %}} +**NOTE**: When you use `sensuctl command exec`, the [environment variables](../environment-variables) are passed to the command. +{{% /notice %}} + +For example: + +{{< code shell >}} +sensuctl command exec --cache-dir /tmp -- -- --= +{{< /code >}} + +Sensuctl will parse the --cache-dir flag, but bin/entrypoint will parse all flags after the ` -- `. + +In this example, the full command run by sensuctl exec would be: + +{{< code shell >}} +bin/entrypoint -- --= +{{< /code >}} + +### List commands + +To list installed sensuctl commands: + +{{< code shell >}} +sensuctl command list +{{< /code >}} + +Replace `` with the flags you want to use. +Run `sensuctl command list -h` to view flags. +Flags are optional and apply only to the `list` command. + +### Delete commands + +To delete sensuctl commands: + +{{< code shell >}} +sensuctl command delete +{{< /code >}} + +Replace `` with a unique name for the command. +For example, for the [sensu/sensu-ec2-handler][3], you might use the alias `sensu-ec2-handler`. +`` is required. + +Replace `` with the flags you want to use. +Run `sensuctl command delete -h` to view flags. +Flags are optional and apply only to the `delete` command. + + +[1]: https://bonsai.sensu.io/ +[3]: https://bonsai.sensu.io/assets/sensu/sensu-ec2-handler +[4]: https://bonsai.sensu.io/assets/sensu/sensu-influxdb-handler diff --git a/content/sensu-go/6.12/versions.md b/content/sensu-go/6.12/versions.md new file mode 100644 index 0000000000..0c3818d541 --- /dev/null +++ b/content/sensu-go/6.12/versions.md @@ -0,0 +1,221 @@ +--- +title: "Supported versions" +linkTitle: "Supported Versions" +description: "Get details about Sensu's supported versions of official distributions, including packages, Docker images, and binary-only distributions." +version: "6.12" +weight: -30 +offline: false +toc: false +product: "Sensu Go" +menu: "sensu-go-6.12" +--- + +Update Sensu frequently to stay in sync with the latest features and fixes. +Read [Upgrade Sensu][1] to upgrade to the latest version. + +Sensu supports the latest versions of official distributions, including [packages][66], [Docker images][68], and [binary-only distributions][67]. +Learn more about Sensu [licensing and support][2]. + +This table lists the supported versions of Sensu Go with links to active documentation (for supported versions) and offline documentation artifacts (for versions that are not supported). + +{{% notice note %}} +**NOTE**: We provide support and documentation for Sensu versions according to the [Sensu Enterprise Support Services Agreement](https://sensu.io/licenses/sensu-support-services#4.-software-releases.). +{{% /notice %}} + +| Version | Release date | Status | | +| ------- | -------------- | --------- | --- | +6.12.0 | [November 13, 2024][100] | Supported | Download Offline Docs +6.11.0 | [January 31, 2024][99] | Supported | Download Offline Docs +6.10.0 | [May 23, 2023][98] | Supported | Download Offline Docs +6.9.2 | [March 8, 2023][97] | Supported | Download Offline Docs +6.9.1 | [December 1, 2022][96] | Supported | Download Offline Docs +6.9.0 | [November 1, 2022][95] | Supported | Download Offline Docs +6.8.2 | [October 6, 2022][94] | Not supported | Download Offline Docs +6.8.1 | [September 13, 2022][93] | Not supported | Download Offline Docs +6.8.0 | [August 29, 2022][92] | Not supported | Download Offline Docs +6.7.5 | [August 10, 2022][91] | Not supported | Download Offline Docs +6.7.4 | [July 15, 2022][90] | Not supported | Download Offline Docs +6.7.3 | [July 7, 2022][89] | Not supported | Download Offline Docs +6.7.2 | [May 12, 2022][88] | Not supported | Download Offline Docs +6.7.1 | [April 28, 2022][87] | Not supported | Download Offline Docs +6.7.0 | [April 21, 2022][86] | Not supported | Download Offline Docs +6.6.6 | [February 16, 2022][85] | Not supported | Download Offline Docs +6.6.5 | [February 3, 2022][84] | Not supported | Download Offline Docs +6.6.4 | [January 26, 2022][83] | Not supported | Download Offline Docs +6.6.3 | [December 16, 2021][82] | Not supported | Download Offline Docs +6.6.2 | [December 8, 2021][81] | Not supported | Download Offline Docs +6.6.1 | [November 29, 2021][80] | Not supported | Download Offline Docs +6.6.0 | [November 25, 2021][79] | Not supported | Download Offline Docs +6.5.5 | [November 22, 2021][78] | Not supported | Download Offline Docs +6.5.4 | [October 30, 2021][77] | Not supported | Download Offline Docs +6.5.3 | [October 29, 2021][76] | Not supported | Download Offline Docs +6.5.2 | [October 28, 2021][75] | Not supported | Download Offline Docs +6.5.1 | [October 20, 2021][74] | Not supported | Download Offline Docs +6.5.0 | [October 13, 2021][73] | Not supported | Download Offline Docs +6.4.3 | [September 1, 2021][72] | Not supported | Download Offline Docs +6.4.2 | [August 31, 2021][71] | Not supported | Download Offline Docs +6.4.1 | [August 25, 2021][70] | Not supported | Download Offline Docs +6.4.0 | [June 28, 2021][69] | Not supported | Download Offline Docs +6.3.0 | [May 26, 2021][65] | Not supported | Download Offline Docs +6.2.7 | [April 1, 2021][64] | Not supported | Download Offline Docs +6.2.6 | [March 25, 2021][63] | Not supported | Download Offline Docs +6.2.5 | [February 2, 2021][60] | Not supported | Download Offline Docs +6.2.4 | [January 28, 2021][59] | Not supported | Download Offline Docs +6.2.3 | [January 21, 2021][58] | Not supported | Download Offline Docs +6.2.2 | [January 14, 2021][57] | Not supported | Download Offline Docs +6.2.1 | [January 11, 2021][56] | Not supported | Download Offline Docs +6.2.0 | [December 17, 2020][55] | Not supported | Download Offline Docs +6.1.4 | [December 16, 2020][54] | Not Supported | Download Offline Docs +6.1.3 | [November 9, 2020][53] | Not Supported | Download Offline Docs +6.1.2 | [October 28, 2020][52] | Not Supported | Download Offline Docs +6.1.1 | [October 22, 2020][51] | Not Supported | Download Offline Docs +6.1.0 | [October 5, 2020][49] | Not Supported | Download Offline Docs +6.0.0 | [August 10, 2020][47] | Not supported | Download Offline Docs +5.21.5 | [March 25, 2021][62] | Not supported | Download Offline Docs +5.21.4 | [March 9, 2021][61] | Not supported | Download Offline Docs +5.21.3 | [October 14, 2020][50] | Not supported | Download Offline Docs +5.21.2 | [August 31, 2020][48] | Not supported | Download Offline Docs +5.21.1 | [August 5, 2020][46] | Not supported | Download Offline Docs +5.21.0 | [June 15, 2020][45] | Not supported | Download Offline Docs +5.20.2 | [May 26, 2020][44] | Not supported | Download Offline Docs +5.20.1 | [May 15, 2020][43] | Not supported | Download Offline Docs +5.20.0 | [May 12, 2020][42] | Not supported | Download Offline Docs +5.19.3 | [May 4, 2020][41] | Not supported | Download Offline Docs +5.19.2 | [April 27, 2020][40] | Not supported | Download Offline Docs +5.19.1 | [April 13, 2020][39] | Not supported | Download Offline Docs +5.19.0 | [March 30, 2020][38] | Not supported | Download Offline Docs +5.18.1 | [March 10, 2020][37] | Not supported | Download Offline Docs +5.18.0 | [February 25, 2020][36] | Not supported | Download Offline Docs +5.17.2 | [February 19, 2020][35] | Not supported | Download Offline Docs +5.17.1 | [January 31, 2020][34] | Not supported | Download Offline Docs +5.17.0 | [January 28, 2020][33] | Not supported | Download Offline Docs +5.16.1 | [December 18, 2019][32] | Not supported | Download Offline Docs +5.16.0 | [December 16, 2019][31] | Not supported | Download Offline Docs +5.15.0 | [November 19, 2019][30] | Not supported | Download Offline Docs +5.14.2 | [November 4, 2019][29] | Not supported | Download Offline Docs +5.14.1 | [October 16, 2019][28] | Not supported | Download Offline Docs +5.14.0 | [October 4, 2019][27] | Not supported | Download Offline Docs +5.13.2 | [September 19, 2019][26] | Not supported | Download Offline Docs +5.13.1 | [September 10, 2019][25] | Not supported | Download Offline Docs +5.13.0 | [September 9, 2019][24] | Not supported | Download Offline Docs +5.12.0 | [August 26, 2019][23] | Not supported | Download Offline Docs +5.11.1 | [July 17, 2019][22] | Not supported | Download Offline Docs +5.11.0 | [July 10, 2019][21] | Not supported | Download Offline Docs +5.10.2 | [June 27, 2019][20] | Not supported | Download Offline Docs +5.10.1 | [June 25, 2019][19] | Not supported | Download Offline Docs +5.10.0 | [June 19, 2019][18] | Not supported | Download Offline Docs +5.9.0 | [May 29, 2019][17] | Not supported | Download Offline Docs +5.8.0 | [May 22, 2019][16] | Not supported | Download Offline Docs +5.7.0 | [May 9, 2019][15] | Not supported | Download Offline Docs +5.6.0 | [April 30, 2019][14] | Not supported | Download Offline Docs +5.5.1 | [April 17, 2019][13] | Not supported | Download Offline Docs +5.5.0 | [April 4, 2019][12] | Not supported | Download Offline Docs +5.4.0 | [March 27, 2019][11] | Not supported | Download Offline Docs +5.3.0 | [March 11, 2019][10] | Not supported | Download Offline Docs +5.2.1 | [February 11, 2019][9] | Not supported | Download Offline Docs +5.2.0 | [February 7, 2019][8] | Not supported | Download Offline Docs +5.1.1 | [January 24, 2019][7] | Not supported | Download Offline Docs +5.1.0 | [December 19, 2018][6] | Not supported | Download Offline Docs +5.0.1 | [December 12, 2018][5] | Not supported | Download Offline Docs +5.0.0 | [December 5, 2018][4] | Not supported | Download Offline Docs + +[1]: https://docs.sensu.io/sensu-go/latest/operations/maintain-sensu/upgrade/ +[2]: https://sensu.io/features/compare +[3]: https://sensu.io/licenses/sensu-support-services#4.-software-releases. +[4]: https://docs.sensu.io/sensu-go/latest/release-notes/#500-release-notes +[5]: https://docs.sensu.io/sensu-go/latest/release-notes/#501-release-notes +[6]: https://docs.sensu.io/sensu-go/latest/release-notes/#510-release-notes +[7]: https://docs.sensu.io/sensu-go/latest/release-notes/#511-release-notes +[8]: https://docs.sensu.io/sensu-go/latest/release-notes/#520-release-notes +[9]: https://docs.sensu.io/sensu-go/latest/release-notes/#521-release-notes +[10]: https://docs.sensu.io/sensu-go/latest/release-notes/#530-release-notes +[11]: https://docs.sensu.io/sensu-go/latest/release-notes/#540-release-notes +[12]: https://docs.sensu.io/sensu-go/latest/release-notes/#550-release-notes +[13]: https://docs.sensu.io/sensu-go/latest/release-notes/#551-release-notes +[14]: https://docs.sensu.io/sensu-go/latest/release-notes/#560-release-notes +[15]: https://docs.sensu.io/sensu-go/latest/release-notes/#570-release-notes +[16]: https://docs.sensu.io/sensu-go/latest/release-notes/#580-release-notes +[17]: https://docs.sensu.io/sensu-go/latest/release-notes/#590-release-notes +[18]: https://docs.sensu.io/sensu-go/latest/release-notes/#5100-release-notes +[19]: https://docs.sensu.io/sensu-go/latest/release-notes/#5101-release-notes +[20]: https://docs.sensu.io/sensu-go/latest/release-notes/#5102-release-notes +[21]: https://docs.sensu.io/sensu-go/latest/release-notes/#5110-release-notes +[22]: https://docs.sensu.io/sensu-go/latest/release-notes/#5111-release-notes +[23]: https://docs.sensu.io/sensu-go/latest/release-notes/#5120-release-notes +[24]: https://docs.sensu.io/sensu-go/latest/release-notes/#5130-release-notes +[25]: https://docs.sensu.io/sensu-go/latest/release-notes/#5131-release-notes +[26]: https://docs.sensu.io/sensu-go/latest/release-notes/#5132-release-notes +[27]: https://docs.sensu.io/sensu-go/latest/release-notes/#5140-release-notes +[28]: https://docs.sensu.io/sensu-go/latest/release-notes/#5141-release-notes +[29]: https://docs.sensu.io/sensu-go/latest/release-notes/#5142-release-notes +[30]: https://docs.sensu.io/sensu-go/latest/release-notes/#5150-release-notes +[31]: https://docs.sensu.io/sensu-go/latest/release-notes/#5160-release-notes +[32]: https://docs.sensu.io/sensu-go/latest/release-notes/#5161-release-notes +[33]: https://docs.sensu.io/sensu-go/latest/release-notes/#5170-release-notes +[34]: https://docs.sensu.io/sensu-go/latest/release-notes/#5171-release-notes +[35]: https://docs.sensu.io/sensu-go/latest/release-notes/#5172-release-notes +[36]: https://docs.sensu.io/sensu-go/latest/release-notes/#5180-release-notes +[37]: https://docs.sensu.io/sensu-go/latest/release-notes/#5181-release-notes +[38]: https://docs.sensu.io/sensu-go/latest/release-notes/#5190-release-notes +[39]: https://docs.sensu.io/sensu-go/latest/release-notes/#5191-release-notes +[40]: https://docs.sensu.io/sensu-go/latest/release-notes/#5192-release-notes +[41]: https://docs.sensu.io/sensu-go/latest/release-notes/#5193-release-notes +[42]: https://docs.sensu.io/sensu-go/latest/release-notes/#5200-release-notes +[43]: https://docs.sensu.io/sensu-go/latest/release-notes/#5201-release-notes +[44]: https://docs.sensu.io/sensu-go/latest/release-notes/#5202-release-notes +[45]: https://docs.sensu.io/sensu-go/latest/release-notes/#5210-release-notes +[46]: https://docs.sensu.io/sensu-go/latest/release-notes/#5211-release-notes +[47]: https://docs.sensu.io/sensu-go/latest/release-notes/#600-release-notes +[48]: https://docs.sensu.io/sensu-go/latest/release-notes/#5212-release-notes +[49]: https://docs.sensu.io/sensu-go/latest/release-notes/#610-release-notes +[50]: https://docs.sensu.io/sensu-go/latest/release-notes/#5213-release-notes +[51]: https://docs.sensu.io/sensu-go/latest/release-notes/#611-release-notes +[52]: https://docs.sensu.io/sensu-go/latest/release-notes/#612-release-notes +[53]: https://docs.sensu.io/sensu-go/latest/release-notes/#613-release-notes +[54]: https://docs.sensu.io/sensu-go/latest/release-notes/#614-release-notes +[55]: https://docs.sensu.io/sensu-go/latest/release-notes/#620-release-notes +[56]: https://docs.sensu.io/sensu-go/latest/release-notes/#621-release-notes +[57]: https://docs.sensu.io/sensu-go/latest/release-notes/#622-release-notes +[58]: https://docs.sensu.io/sensu-go/latest/release-notes/#623-release-notes +[59]: https://docs.sensu.io/sensu-go/latest/release-notes/#624-release-notes +[60]: https://docs.sensu.io/sensu-go/latest/release-notes/#625-release-notes +[61]: https://docs.sensu.io/sensu-go/latest/release-notes/#5214-release-notes +[62]: https://docs.sensu.io/sensu-go/latest/release-notes/#5215-release-notes +[63]: https://docs.sensu.io/sensu-go/latest/release-notes/#626-release-notes +[64]: https://docs.sensu.io/sensu-go/latest/release-notes/#627-release-notes +[65]: https://docs.sensu.io/sensu-go/latest/release-notes/#630-release-notes +[66]: ../platforms/#supported-packages +[67]: ../platforms/#binary-only-distributions +[68]: ../platforms/#docker-images +[69]: https://docs.sensu.io/sensu-go/latest/release-notes/#640-release-notes +[70]: https://docs.sensu.io/sensu-go/latest/release-notes/#641-release-notes +[71]: https://docs.sensu.io/sensu-go/latest/release-notes/#642-release-notes +[72]: https://docs.sensu.io/sensu-go/latest/release-notes/#643-release-notes +[73]: https://docs.sensu.io/sensu-go/latest/release-notes/#650-release-notes +[74]: https://docs.sensu.io/sensu-go/latest/release-notes/#651-release-notes +[75]: https://docs.sensu.io/sensu-go/latest/release-notes/#652-release-notes +[76]: https://docs.sensu.io/sensu-go/latest/release-notes/#653-release-notes +[77]: https://docs.sensu.io/sensu-go/latest/release-notes/#654-release-notes +[78]: https://docs.sensu.io/sensu-go/latest/release-notes/#655-release-notes +[79]: https://docs.sensu.io/sensu-go/latest/release-notes/#660-release-notes +[80]: https://docs.sensu.io/sensu-go/latest/release-notes/#661-release-notes +[81]: https://docs.sensu.io/sensu-go/latest/release-notes/#662-release-notes +[82]: https://docs.sensu.io/sensu-go/latest/release-notes/#663-release-notes +[83]: https://docs.sensu.io/sensu-go/latest/release-notes/#664-release-notes +[84]: https://docs.sensu.io/sensu-go/latest/release-notes/#665-release-notes +[85]: https://docs.sensu.io/sensu-go/latest/release-notes/#666-release-notes +[86]: https://docs.sensu.io/sensu-go/latest/release-notes/#670-release-notes +[87]: https://docs.sensu.io/sensu-go/latest/release-notes/#671-release-notes +[88]: https://docs.sensu.io/sensu-go/latest/release-notes/#672-release-notes +[89]: https://docs.sensu.io/sensu-go/latest/release-notes/#673-release-notes +[90]: https://docs.sensu.io/sensu-go/latest/release-notes/#674-release-notes +[91]: https://docs.sensu.io/sensu-go/latest/release-notes/#675-release-notes +[92]: https://docs.sensu.io/sensu-go/latest/release-notes/#680-release-notes +[93]: https://docs.sensu.io/sensu-go/latest/release-notes/#681-release-notes +[94]: https://docs.sensu.io/sensu-go/latest/release-notes/#682-release-notes +[95]: https://docs.sensu.io/sensu-go/latest/release-notes/#690-release-notes +[96]: https://docs.sensu.io/sensu-go/latest/release-notes/#691-release-notes +[97]: https://docs.sensu.io/sensu-go/latest/release-notes/#692-release-notes +[98]: https://docs.sensu.io/sensu-go/latest/release-notes/#6100-release-notes +[99]: https://docs.sensu.io/sensu-go/latest/release-notes/#6110-release-notes +[100]: https://docs.sensu.io/sensu-go/latest/release-notes/#6120-release-notes diff --git a/content/sensu-go/6.12/web-ui/_index.md b/content/sensu-go/6.12/web-ui/_index.md new file mode 100644 index 0000000000..42f2266ea4 --- /dev/null +++ b/content/sensu-go/6.12/web-ui/_index.md @@ -0,0 +1,95 @@ +--- +title: "Web UI" +description: "Use the Sensu web UI to get an overview of the health of systems under observability, with detail pages for Sensu resources and user-friendly management tools." +weight: 50 +product: "Sensu Go" +version: "6.12" +layout: "single" +menu: + sensu-go-6.12: + identifier: web-ui +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access the Sensu web UI in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../commercial/). +{{% /notice %}} + +The Sensu backend includes the **Sensu web UI**: a unified view of your events, entities, and checks with user-friendly tools that provide single-pane-of-glass visibility and reduce alert fatigue. + + + +The web UI homepage provides a high-level overview of the overall health of the systems under Sensu's management, with a summary of active incidents, the number of incidents by severity, the types of entities under management, and the numbers of entities and incidents per namespace. + +{{< figure src="/images/go/web_ui_index/web_ui_660.png" alt="Sensu web UI homepage" link="/images/go/web_ui_index/web_ui_660.png" target="_blank" >}} + +## Access the web UI + +After you [start the Sensu backend][1], you can access the web UI in your browser by visiting http://localhost:3000. + +{{% notice note %}} +**NOTE**: You may need to replace `localhost` with the hostname or IP address where the Sensu backend is running. +{{% /notice %}} + +## Sign in to the web UI + +Sign in to the web UI with the username and password you used to configure [sensuctl][2]. + +The web UI uses your username and password to obtain access and refresh tokens via the Sensu [/auth API][7]. +The access and refresh tokens are [JSON Web Tokens (JWTs)][2] that Sensu issues to record the details of users' authenticated Sensu sessions. +The backend digitally signs these tokens, and the tokens can't be changed without invalidating the signature. +The access and refresh tokens are saved in your browser's local storage. + +The web UI complies with Sensu role-based access control (RBAC), so individual users can view information according to their access configurations. +Read the [RBAC reference][3] for [default user credentials][4] and instructions for [creating new users][5]. + +### Backend log messages for web UI sign-in + +Upon successful login, Sensu logs an INFO message in the backend log with details about the user and provider. +For unsuccessful login attempts, Sensu logs an ERROR message upon authentication failure, along with the username that was tried. + +Read [Service logging][10] for more information about the backend log and log levels. + +## View system information + +Press `CTRL .` in the web UI to open the system information modal and view information about your Sensu backend and etcd or PostgreSQL datastore. +For users with permission to create or update licenses, the system information modal includes license expiration information. + +### License expiration banner + +A banner appears at the top of the web UI screen when your organization's license is expiring: + +{{< figure src="/images/go/web_ui_index/license_expiration_banner.png" alt="Sensu web UI homepage" link="/images/go/web_ui_index/license_expiration_banner.png" target="_blank" >}} + +The banner is only visible to [users][6] who have read access to your organization's license. + +By default, the banner starts appearing when the license expiration is 30 days away. +To adjust the number of days before license expiration to begin displaying the banner, use the [license_expiry_reminder][9] web UI configuration attribute. + +## Use the implicit OR operator + +On the Sensu web UI homepage, you can use the search function to limit the display by cluster and namespace. +If you specify the same attribute twice with different values, Sensu automatically applies a logical OR operator to your search. + +For example, suppose you enter two search expressions in the search bar on the web UI homepage: `namespace: devel_1` and `namespace: devel_2`. +In this case, the web UI homepage will display all data for both namespaces: `devel_1` and `devel_2`. + +## Change web UI themes + +Use the preferences menu to change the theme or switch to the dark theme. + +## Troubleshoot web UI errors + +Read [Troubleshoot Sensu][8] to resolve and investigate web UI errors. + + +[1]: ../observability-pipeline/observe-schedule/backend#start-the-service +[2]: ../sensuctl/#first-time-setup-and-authentication +[3]: ../operations/control-access/rbac/ +[4]: ../operations/control-access/rbac#default-users +[5]: ../operations/control-access/rbac#create-users +[6]: ../operations/control-access/rbac/#users +[7]: ../api/other/auth/ +[8]: ../operations/maintain-sensu/troubleshoot/#web-ui-errors +[9]: ../web-ui/webconfig-reference/#license_expiry_reminder +[10]: ../operations/maintain-sensu/troubleshoot/#service-logging diff --git a/content/sensu-go/6.12/web-ui/bsm-module.md b/content/sensu-go/6.12/web-ui/bsm-module.md new file mode 100644 index 0000000000..0334d33b01 --- /dev/null +++ b/content/sensu-go/6.12/web-ui/bsm-module.md @@ -0,0 +1,88 @@ +--- +title: "Build business service monitoring" +linkTitle: "Build Business Service Monitoring" +description: "Use the Sensu web UI module to create, configure, edit, and delete business service monitoring (BSM) service entities, service components, and rule templates." +weight: 110 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: web-ui +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access the web UI and business service monitoring (BSM) in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../commercial/). +{{% /notice %}} + +{{% notice note %}} +**NOTE**: Business service monitoring (BSM) is in public preview and is subject to change. +{{% /notice %}} + +The Sensu web UI includes a module to help you build and configure business service monitoring (BSM) [service entities][4] with [service components][1] and [rule templates][2]. + +## Build a business service + +{{% notice note %}} +**NOTE**: BSM requires [PostgreSQL](../../operations/deploy-sensu/scale-event-storage/) to achieve high event throughput. +For this reason, the web UI will display a PostgreSQL prompt instead of the BSM module until you configure a PostgreSQL datastore. +{{% /notice %}} + +To build a business service in the web UI module: + +1. Click ![services icon](/images/go/bsm_module/web_ui_services_icon_660.png) in the left navigation menu to open the Services page. +2. Click **ADD NEW SERVICE** to open the Create New Service dialog window. +3. Enter a name for the service entity. +4. Enter labels and annotations, if desired. +5. Click **Submit**. + +The updated Services page will include a tile for the new service: + +{{< figure src="/images/go/bsm_module/create_service_670.gif" alt="Add a new business service with the web UI module" link="/images/go/bsm_module/create_service_670.gif" target="_blank" >}} + +The business service itself is an entity with the class `service`, so it will also be listed on the [Entities page][3]. + +To add service components to a business service: + +1. Click ⋮ for the business service. +2. Select **+ New** from the drop-down menu to open the Configure New Service Component dialog window. +3. Enter a name for the service component. +4. Enter labels and annotations, if desired. +5. Enter query selectors to describe the events that each monitoring rule should process for the service component. +6. Select the rule template you wish to use and a unique name to use for the rule-specific events. +7. Enter values for the arguments to pass to the rule template. +Available arguments will vary for different rule templates. +8. Specify the type of check scheduling the service component should use (interval or cron) as well as the desired interval in seconds or cron scheduling statement. +9. Specify the handlers the service component should use. +10. Click **Submit**. + +The updated business service tile will include the service component: + +{{< figure src="/images/go/bsm_module/create_service_component_670.gif" alt="Add a new service component to a business service with the web UI module" link="/images/go/bsm_module/create_service_component_670.gif" target="_blank" >}} + +## View and manage business services + +After you create a business service by any means (web UI, API, or sensuctl), it will be listed in the web UI Services page until you delete it. + +Click the business service name to view its events and other related details and edit, silence, or delete the service: + +{{< figure src="/images/go/bsm_module/business_service_detail_page_670.png" alt="View the business service detail page" link="/images/go/bsm_module/business_service_detail_page_670.png" target="_blank" >}} + +To edit, add components to, or delete a business service, click ⋮ at the top-right corner of the service's tile. + +## View and manage service components + +After you add a service component to a business service, it will be listed on the business service tile in the web UI Services page until you delete it. +To edit or delete a service component, click ⋮ at the right of the component's name: + +{{< figure src="/images/go/bsm_module/edit_service_component_670.png" alt="Edit a service component" link="/images/go/bsm_module/edit_service_component_670.png" target="_blank" >}} + +Click the service component name to view its events and other related details. +You can also edit, silence, and delete the component from the detail page. + + +[1]: ../../observability-pipeline/observe-schedule/service-components/ +[2]: ../../observability-pipeline/observe-schedule/rule-templates/ +[3]: ../view-manage-resources/#manage-entities +[4]: ../../observability-pipeline/observe-entities/#service-entities diff --git a/content/sensu-go/6.12/web-ui/search.md b/content/sensu-go/6.12/web-ui/search.md new file mode 100644 index 0000000000..f93e9fee65 --- /dev/null +++ b/content/sensu-go/6.12/web-ui/search.md @@ -0,0 +1,256 @@ +--- +title: "Search in the web UI" +linkTitle: "Search in the Web UI" +description: "Search and filter in the Sensu web UI and build customized views of your events, entities, silences, checks, handlers, filters, and mutators pages." +weight: 70 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: web-ui +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access the web UI, basic and advanced web UI searching, and saved searches in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../commercial/). +{{% /notice %}} + +The Sensu web UI includes basic search and filtering functions you can use to build customized views of your Sensu resources. +Sensu also supports advanced web UI searches based on a wider range of resource attributes and custom labels as a [commercial feature][1]. + +When you apply a search to a web UI page, it creates a unique link for the page of search results. +You can bookmark these links and share your favorite search combinations. +You can also [save your favorite searches][8]. + +## Events and entities search limits + +If you use etcd for event storage, web UI search queries on the events and entities pages will stop after returning a certain number of matches. +Without these limits, the search operation can diminish cluster health. + +If a web UI search reaches the limit for the events or entities page, the results count at the bottom-right corner of the page will indicate that the total number of matches exceeds the number of results listed. + +### Events search limit + +On the events page, if you use etcd for event storage, search queries will return a maximum of 50,000 events. +For example, if you use etcd for event storage and you search in a namespace that has more than 50,000 matching events, the search results will not include matching events beyond the first 50,000. + +### Entities search limit + +If you use etcd for event storage, search queries on the entities page will stop after retrieving approximately 500 matches. +As a result, if your search matches more than 500 entities, the total results count at the bottom-right corner of the entities page will not accurately reflect the number of matching entities. + +## Search operators + +Web UI search supports two equality-based operators, two set-based operators, one substring matching operator, and one logical operator. + +| operator | description | example | +| --------- | ------------------ | ---------------------- | +| `==` | Equality | `check.publish == "true"` +| `!=` | Inequality | `check.namespace != "default"` +| `in` | Included in | `"linux" in check.subscriptions` +| `notin` | Not included in | `"slack" notin check.handlers` +| `matches` | Substring matching | `check.name matches "linux-"` +| `&&` | Logical AND | `check.publish == "true" && "slack" in check.handlers` + +For details about operators, read about the [API response filtering operators][7]. + +## Use quick search + +The web UI quick search allows you to query and filter Sensu resources without using search syntax. +Type your search term into the search field on any page of the web UI and press `Enter`. +Sensu will auto-complete a simple search statement for the resources on that page using substring matching. + +For example, on the Events page in the web UI, if you type `mysql` into the search field, Sensu will auto-complete the search statement to `event.check.name matches "mysql"`. + +## Create basic searches + +Sensu includes these basic search functions: + +- **Events page**: search by entity, check, status, and silenced/unsilenced. +- **Entities page**: search by entity class and subscription. +- **Silences page**: search by check and subscription. +- **Checks page**: search by subscription and published/unpublished. +- **Handlers page**: search by handler type. +- **Filters page**: search by action. + +If you are using the [basic web UI search functions][5], you can create a search by clicking in the search bar at the top of the web UI page: + +1. In the web UI, open the page of resources you want to search. +2. Click in the search bar at the top of the web UI page. +3. Select the attribute you want to search for from the dropdown list of options. +4. Click in the search bar again and select the search to apply. +5. Press **Return/Enter**. + +{{% notice note %}} +**NOTE**: You do not need to specify a resource type in web UI search because you must navigate to the resource page *before* you construct the search. +{{% /notice %}} + +## Create advanced searches + +Sensu supports advanced web UI searches using a wider range of attributes, including custom labels. +You can use the same methods, fields, and examples for web UI searches as for [API response filtering][3], with some [syntax differences][4]. + +To search resources based on fields and labels, you'll write a brief search statement. +Depending on the [operator][9] you're using, the web UI search syntax is either: + +{{< code text >}} + +{{< /code >}} + +or + +{{< code text >}} + +{{< /code >}} + +Fields are specific [resource attributes][2] in dot notation. +For example, this search will retrieve all events for entities with the `linux` subscription: + +{{< code shell >}} +"linux" in event.entity.subscriptions +{{< /code >}} + +This search will retrieve all events that whose status is *not* equal to `passing`: + +{{< code shell >}} +event.check.state != "passing" +{{< /code >}} + +To display only events for checks with the subscription `webserver`, enter this search statement on the **Events page**: + +{{< code shell >}} +"webserver" in event.check.subscriptions +{{< /code >}} + +To display only checks that use the `slack` handler, enter this search statement on the **Checks page**: + +{{< code shell >}} +"slack" in check.handlers +{{< /code >}} + +## Search for numbers or special characters + +If you are searching for a value that begins with a number, place the value in single or double quotes: + +{{< code shell >}} +entity.name == '1b04994n' +entity.name == "1b04994n" +{{< /code >}} + +Likewise, to search string values that include special characters like hyphens and underscores, place the value in single or double quotes: + +{{< code shell >}} +entity.labels.region == 'us-west-1' +entity.labels.region == "us-west-1" +{{< /code >}} + +To display only events at `2` (CRITICAL) status: + +{{< code shell >}} +event.check.status == "2" +{{< /code >}} + +## Search for labels + +Labels are treated like any other field in web UI searches. + +For example, to search based on a check label `version`, use: + +{{< code shell >}} +check.labels.version matches "7" +{{< /code >}} + +To display only checks with the `type` label set to `server`, enter this search statement on the **Checks page**: + +{{< code shell >}} +check.labels.type == "server" +{{< /code >}} + +To search for entities that are labeled for any region in the US (for example, `us-east-1`, `us-west-1`, and so on): + +{{< code shell >}} +entity.labels.region matches "us" +{{< /code >}} + +{{% notice note %}} +**NOTE**: Web UI searches for label names that include hyphens are not supported. +Searches that include a hyphenated label name, such as `entity.labels.imported-by`, will return an unsupported token error. +{{% /notice %}} + +### Search for event labels + +For label-based event searches, the web UI merges check and entity labels into a single search term: `event.labels.[KEY]`. + +For example, to display events with the `type` label set to `server`, enter this search statement on the **Events** page: + +{{< code shell >}} +event.labels.type == "server" +{{< /code >}} + +This search will retrieve events with the `type` label set to `server`, no matter whether the label is defined in the event's corresponding check or entity configuration. + +## Use the logical AND operator + +To use the logical AND operator (`&&`) to return checks that include a `linux` subscription and the `slack` handler: + +{{< code shell >}} +"linux" in check.subscriptions && "slack" in check.handlers +{{< /code >}} + +To return events that include a `windows` check subscription and any email handler: + +{{< code shell >}} +"windows" in event.check.subscriptions && event.check.handlers matches "email" +{{< /code >}} + +## Save a search + +To save a web UI search: + +1. [Create a web UI search][4]. +2. Click ![save icon](/images/go/bsm_module/save_icon_660.png) at the right side of the search bar. +3. Click **Save this search**. +4. Type the name you want to use for the saved search. +5. Press **Return/Enter**. + +Sensu saves your web UI searches to etcd in a [namespaced resource][11] named `searches`. +To recall a saved web UI search, a Sensu user must be assigned to a [role][12] that includes permissions for both the `searches` resource and the namespace where you save the search. + +The role-based access control (RBAC) reference includes [example workflows][13] that demonstrate how to configure a user's roles and role bindings to include full permissions for namespaced resources, including saved searches. + +### Recall a saved search + +To recall a saved search, click ![save icon](/images/go/bsm_module/save_icon_660.png) at the right side of the search bar and select the name of the search you want to recall. + +You can combine an existing saved search with a new search to create a new saved search. +To do this, recall a saved search, add the new search statement in the search bar, and [save the combination as a new saved search][8]. + +### Delete a saved search + +To delete a saved search: + +1. Click ![save icon](/images/go/bsm_module/save_icon_660.png) at the right side of the search bar. +2. Find the saved search you want to delete and click the ![delete icon](/images/go/bsm_module/delete_icon_660.png) next to it. + +## Use the sort function + +Use the **SORT** dropdown menu to sort search results. +You can sort all resources by name, but events and silences have additional sorting options: + +- **Events page**: sort by last OK, severity, timestamp, and entity. +- **Silences page**: sort by start date. + + +[1]: ../../commercial/ +[2]: ../../api/#field-selector +[3]: ../../api/#response-filtering +[4]: #search-for-numbers-or-special-characters +[5]: #create-basic-searches +[6]: ../../api/#label-selector +[7]: ../../api/#filter-operators +[8]: #save-a-search +[9]: #search-operators +[11]: ../../operations/control-access/rbac/#namespaced-resource-types +[12]: ../../operations/control-access/rbac/#roles-and-cluster-roles +[13]: ../../operations/control-access/rbac/#create-a-role-and-role-binding diff --git a/content/sensu-go/6.12/web-ui/searches-reference.md b/content/sensu-go/6.12/web-ui/searches-reference.md new file mode 100644 index 0000000000..0a072ccc13 --- /dev/null +++ b/content/sensu-go/6.12/web-ui/searches-reference.md @@ -0,0 +1,472 @@ +--- +title: "Searches reference" +linkTitle: "Searches Reference" +reference_title: "Searches" +type: "reference" +description: "Read this reference to use the saved searches feature in the Sensu web UI to create, update, and delete saved searches." +weight: 130 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: web-ui +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access the web UI in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../commercial/). +{{% /notice %}} + +With the saved searches feature in the web UI, you can apply search parameters to your entities, events, and resources and save them to etcd in a [namespaced resource][2] named `searches`. + +The saved searches feature is designed to be used directly in the [web UI][3]. +However, you can create, retrieve, update, and delete saved searches with [enterprise/searches/v1 API endpoints][4]. + +## Search for events with any status except passing + +The following saved search will retrieve all events that have any status except `passing`: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Search +api_version: searches/v1 +metadata: + name: events-not-passing +spec: + parameters: + - status:incident + - status:warning + - status:critical + - status:unknown + resource: core.v2/Event +{{< /code >}} + +{{< code json >}} +{ + "type": "Search", + "api_version": "searches/v1", + "metadata": { + "name": "events-not-passing" + }, + "spec": { + "parameters": [ + "status:incident", + "status:warning", + "status:critical", + "status:unknown" + ], + "resource": "core.v2/Event" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Search for published checks with a specific subscription and region + +The following saved search will retrieve all published checks for the `us-west-1` region with the `linux` subscription: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: Search +api_version: searches/v1 +metadata: + name: published-checks-linux-uswest +spec: + parameters: + - published:true + - subscription:linux + - 'labelSelector: region == "us-west-1"' + resource: core.v2/CheckConfig +{{< /code >}} + +{{< code json >}} +{ + "type": "Search", + "api_version": "searches/v1", + "metadata": { + "name": "published-checks-linux-uswest" + }, + "spec": { + "parameters": [ + "published:true", + "subscription:linux", + "labelSelector: region == \"us-west-1\"" + ], + "resource": "core.v2/CheckConfig" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Search specification + +### Top-level attributes + +api_version | +-------------|------ +description | Top-level attribute that specifies the Sensu API group and version. For searches in this version of Sensu, the `api_version` should always be `searches/v1`. +required | Required for search entry definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][6]. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +api_version: searches/v1 +{{< /code >}} +{{< code json >}} +{ + "api_version": "searches/v1" +} +{{< /code >}} +{{< /language-toggle >}} + +metadata | +-------------|------ +description | Top-level collection of metadata about the search that includes `name` and `namespace`. The `metadata` map is always at the top level of the search definition. This means that in `wrapped-json` and `yaml` formats, the `metadata` scope occurs outside the `spec` scope. Read [metadata attributes][5] for details. +required | Required for search entry definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][6]. +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +metadata: + name: us-west-server-incidents + namespace: default +{{< /code >}} +{{< code json >}} +{ + "metadata": { + "name": "us-west-server-incidents", + "namespace": "default" + } +} +{{< /code >}} +{{< /language-toggle >}} + +spec | +-------------|------ +description | Top-level map that includes the search [spec attributes][7]. The spec contents will depend on the search parameters you apply and save. +required | Required for silences in `wrapped-json` or `yaml` format for use with [`sensuctl create`][6]. +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +spec: + parameters: + - entity:server-testing + - check:server-health + - status:incident + - labelSelector:region == "us-west-1" + resource: core.v2/Event +{{< /code >}} +{{< code json >}} +{ + "spec": { + "parameters": [ + "entity:server-testing", + "check:server-health", + "status:incident", + "labelSelector:region == \"us-west-1\"" + ], + "resource": "core.v2/Event" + } +} +{{< /code >}} +{{< /language-toggle >}} + +type | +-------------|------ +description | Top-level attribute that specifies the [`sensuctl create`][6] resource type. Searches should always be type `Search`. +required | Required for search entry definitions in `wrapped-json` or `yaml` format for use with [`sensuctl create`][6]. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +type: Search +{{< /code >}} +{{< code json >}} +{ + "type": "Search" +} +{{< /code >}} +{{< /language-toggle >}} + +### Metadata attributes + +| name | | +-------------|------ +description | Search identifier generated from the combination of a subscription name and check name. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +name: us-west-server-incidents +{{< /code >}} +{{< code json >}} +{ + "name": "us-west-server-incidents" +} +{{< /code >}} +{{< /language-toggle >}} + +| namespace | | +-------------|------ +description | Sensu [RBAC namespace][8] that the search belongs to. +required | false +type | String +default | `default` +example | {{< language-toggle >}} +{{< code yml >}} +namespace: default +{{< /code >}} +{{< code json >}} +{ + "namespace": "default" +} +{{< /code >}} +{{< /language-toggle >}} + +### Spec attributes + +parameters | +-------------|------ +description | Parameters the search will apply. +required | true +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +parameters: +- entity:server-testing +- check:server-health +- status:incident +- labelSelector:region == "us-west-1" +{{< /code >}} +{{< code json >}} +{ + "parameters": [ + "entity:server-testing", + "check:server-health", + "status:incident", + "labelSelector:region == \"us-west-1\"" + ] +} +{{< /code >}} +{{< /language-toggle >}} + +resource | +-------------|------ +description | Fully qualified name of the resource included in the search. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +resource: core.v2/Event +{{< /code >}} +{{< code json >}} +{ + "resource": "core.v2/Event" +} +{{< /code >}} +{{< /language-toggle >}} + +#### Parameters + +action | +-------------|------ +description | For event filter searches, the type of filter to include in the search: `allow` or `deny`. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +parameters: +- action:allow +{{< /code >}} +{{< code json >}} +{ + "parameters": [ + "action:allow" + ] +} +{{< /code >}} +{{< /language-toggle >}} + +check | +-------------|------ +description | Name of the check to include in the search. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +parameters: +- check:server-health +{{< /code >}} +{{< code json >}} +{ + "parameters": [ + "check:server-health" + ] +} +{{< /code >}} +{{< /language-toggle >}} + +class | +-------------|------ +description | For entity searches, the entity class to include in the search: `agent` or `proxy`. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +parameters: +- class:agent +{{< /code >}} +{{< code json >}} +{ + "parameters": [ + "class:agent" + ] +} +{{< /code >}} +{{< /language-toggle >}} + +entity | +-------------|------ +description | Name of the entity to include in the search. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +parameters: +- entity:server-testing +{{< /code >}} +{{< code json >}} +{ + "parameters": [ + "entity:server-testing" + ] +} +{{< /code >}} +{{< /language-toggle >}} + +event | +-------------|------ +description | Name of the event to include in the search. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +parameters: +- event:server-testing +{{< /code >}} +{{< code json >}} +{ + "parameters": [ + "event:server-testing" + ] +} +{{< /code >}} +{{< /language-toggle >}} + +published | +-------------|------ +description | If `true`, the search will include only published resources. Otherwise, `false`. +required | false +type | Boolean +example | {{< language-toggle >}} +{{< code yml >}} +parameters: +- published:true +{{< /code >}} +{{< code json >}} +{ + "parameters": [ + "published:true" + ] +} +{{< /code >}} +{{< /language-toggle >}} + +silenced | +-------------|------ +description | If `true`, the search will include only silenced events. Otherwise, `false`. +required | false +type | Boolean +example | {{< language-toggle >}} +{{< code yml >}} +parameters: +- silenced:true +{{< /code >}} +{{< code json >}} +{ + "parameters": [ + "silenced:true" + ] +} +{{< /code >}} +{{< /language-toggle >}} + +status | +-------------|------ +description | Status of the events, entities, or resources to include in the search. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +parameters: +- status:incident +{{< /code >}} +{{< code json >}} +{ + "parameters": [ + "status:incident" + ] +} +{{< /code >}} +{{< /language-toggle >}} + +subscription | +-------------|------ +description | Name of the subscription to include in the search. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +parameters: +- subscription:web +{{< /code >}} +{{< code json >}} +{ + "parameters": [ + "subscription:web" + ] +} +{{< /code >}} +{{< /language-toggle >}} + +type | +-------------|------ +description | For handler searches, the type of hander to include in the search: `pipe`, `set`, `tcp`, or `udp`. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +parameters: +- type:pipe +{{< /code >}} +{{< code json >}} +{ + "parameters": [ + "type:pipe" + ] +} +{{< /code >}} +{{< /language-toggle >}} + + +[2]: ../../operations/control-access/rbac/#namespaced-resource-types +[3]: ../../web-ui/search/#save-a-search +[4]: ../../api/enterprise/searches/ +[5]: #metadata-attributes +[6]: ../../sensuctl/create-manage-resources/#create-resources +[7]: #spec-attributes +[8]: ../../operations/control-access/namespaces/ diff --git a/content/sensu-go/6.12/web-ui/view-manage-resources.md b/content/sensu-go/6.12/web-ui/view-manage-resources.md new file mode 100644 index 0000000000..44f17857e5 --- /dev/null +++ b/content/sensu-go/6.12/web-ui/view-manage-resources.md @@ -0,0 +1,161 @@ +--- +title: "View and manage resources in the web UI" +linkTitle: "View and Manage Resources" +description: "View and manage Sensu resources in the user-friendly web UI, including events, entities, silences, checks, handlers, event filters, and mutators." +weight: 10 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: web-ui +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access the web UI in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../commercial/). +{{% /notice %}} + +You can view and manage Sensu resources in the web UI, including events, entities, silences, checks, handlers, event filters, and mutators. + +## Use the namespace switcher + +Beyond the [homepage][1], the web UI displays events, entities, and resources for a single namespace at a time. +By default, the web UI displays the `default` namespace. + +To switch namespaces, select the menu icon in the upper-left corner or press the `Ctrl+K` keyboard shortcut and choose a namespace from the dropdown. + +{{% notice note %}} +**NOTE**: The namespace switcher will list only the namespaces to which the current user has access. +{{% /notice %}} + +{{< figure src="/images/go/view_manage_resources/web_ui_namespace_switcher_660.png" alt="Sensu web UI namespace switcher" link="/images/go/view_manage_resources/web_ui_namespace_switcher_660.png" target="_blank" >}} + +When you switch to a namespace, the left navigation menu loads so you can select specific pages for events, entities, services, silences, catalog, and configuration, which includes checks, handlers, event filters, and mutators: + +{{< figure src="/images/go/view_manage_resources/web_ui_left_nav_670.png" alt="Sensu web UI left navigation menu" link="/images/go/view_manage_resources/web_ui_left_nav_670.png" target="_blank" >}} + +Click the ☰ icon at the top of the left-navigation menu to expand the menu and display page labels: + +{{< figure src="/images/go/view_manage_resources/expand_web_ui_left_nav_670.png" alt="Sensu web UI with expanded left navigation menu" link="/images/go/view_manage_resources/expand_web_ui_left_nav_670.png" target="_blank" >}} + +## Manage events + +The Events page opens by default when you navigate to a namespace, with an automatic filter to show only events with a non-passing status (i.e. `event.check.state != passing`). +The menu bar at the top of the events list includes several other options for filtering and sorting events: + +{{< figure src="/images/go/view_manage_resources/events_page_filter_sort_670.png" alt="Filter and sort events" link="/images/go/view_manage_resources/events_page_filter_sort_670.png" target="_blank" >}} + +Click the check boxes to select one or more events and resolve, re-run, silence, or delete them directly from the Events page: + +{{< figure src="/images/go/view_manage_resources/group_events_690.png" alt="Select one or more events on the Events page" link="/images/go/view_manage_resources/group_events_690.png" target="_blank" >}} + +Click an event name to view details like status, output, number of occurrences, labels and annotations, related check configuration (if the event was produced by a service check), and entity summary, as well as a timeline that displays the event's last 20 statuses at a glance: + +{{< figure src="/images/go/view_manage_resources/single_event_view_670.gif" alt="View details for a single event" link="/images/go/view_manage_resources/single_event_view_670.gif" target="_blank" >}} + +## Manage entities + +The Entities page provides real-time inventory information for the namespace's endpoints under Sensu management. +The top row of the entities list includes options for filtering and sorting entities on the page: + +{{< figure src="/images/go/view_manage_resources/entities_page_filter_sort_680.png" alt="Filter and sort entities" link="/images/go/view_manage_resources/entities_page_filter_sort_680.png" target="_blank" >}} + +Click the check boxes to select one or more entities and silence or delete them directly from the Entities page: + +{{< figure src="/images/go/view_manage_resources/group_entities_690.png" alt="Select one or more entities on the Entities page" link="/images/go/view_manage_resources/group_entities_690.png" target="_blank" >}} + +Click an entity name to view details about the entity's creator, agent version (for agent entities), subscriptions, labels and annotations, associated events, and properties: + +{{< figure src="/images/go/view_manage_resources/single_entity_view_680.gif" alt="View details for a single entity" link="/images/go/view_manage_resources/single_entity_view_680.gif" target="_blank" >}} + +## Manage services + +The Services page includes a module to help you build and configure service entities with service components and rule templates for business service monitoring (BSM). +Read [Build business service monitoring][2] for details about the web UI BSM module. + +## Manage silences + +Create silences by check or subscription name and clear silences in the web UI Silences page. +The Silences page lists all active silences for the namespace. +The top row of the silences list includes options for filtering and sorting silences on the page: + +{{< figure src="/images/go/view_manage_resources/silences_filter_sort_670.png" alt="Filter and sort silences" link="/images/go/view_manage_resources/silences_filter_sort_670.png" target="_blank" >}} + +Click `+ NEW` to open a dialog window and create silences for individual events, by check or subscription name, or by entity: + +{{< figure src="/images/go/view_manage_resources/silences_dialog_670.gif" alt="Create a new silence in the dialog window" link="/images/go/view_manage_resources/silences_dialog_670.gif" target="_blank" >}} + +You can also silence individual checks and entities from their detail pages in the web UI. + +After you create a silence, it will be listed in the web UI Silences page until you clear the silence or the silence expires. + +## Manage configuration resources + +Under the Configuration menu option, you can access assets, checks, event filters, handlers, mutators, pipelines, role-based access control (RBAC) resources, and secrets. +Each resource page lists the namespace's resources. +The top row of each page includes options for filtering and sorting the listed resources. + +{{< figure src="/images/go/view_manage_resources/configuration_pages_680.gif" alt="Configuration resource pages in the web UI" link="/images/go/view_manage_resources/configuration_pages_680.gif" target="_blank" >}} + +Click a resource name to view the resource's detail page, where you can review more information about the resource and edit or delete it. + +On the Checks page, click the check boxes to select one or more checks to execute, silence, unpublish, or delete them. + +### Execute checks on demand + +You can execute individual checks on demand and on any agent from each check's detail page to test your observability pipeline. + +Click **EXECUTE** to open the Execute Check dialog window: + +{{< figure src="/images/go/view_manage_resources/execute_check_button_670.png" alt="Button for executing a check on demand in the web UI" link="/images/go/view_manage_resources/execute_check_button_670.png" target="_blank" >}} + +In the Execute Check dialog window, you can execute the check according to its existing subscriptions or add and remove subscriptions to execute it on specific agents. + +{{% notice note %}} +**NOTE**: Changing the subscriptions for ad hoc execution in the Execute Check dialog window will not make any changes to the existing subscriptions in the check definition. +{{% /notice %}} + +{{< figure src="/images/go/view_manage_resources/execute_check_dialog_670.png" alt="Execute Check dialog window for executing a check on demand from the web UI" link="/images/go/view_manage_resources/execute_check_dialog_670.png" target="_blank" >}} + +{{% notice note %}} +**NOTE**: If you manually execute a [round robin check](../../observability-pipeline/observe-schedule/checks/#round-robin-checks) in the web UI, Sensu will execute the check on *all* subscribed agents. +After the manual execution, the check will run as scheduled in round robin fashion.

    +To manually execute a round robin check on a single agent, specify the agent's entity name subscription in the Execute Check dialog. +For example, if the entity is named `webserver1`, use the subscription `entity:webserver1`. +{{% /notice %}} + +## View resource data in the web UI + +You can view and copy the YAML or JSON definition for any event, entity, or configuration resource directly in the web UI. + +### View resource data for an event or entity + +To view and copy the YAML and JSON definitions for any event or entity in the web UI: + +1. Open the individual resource page for the event or entity. +2. Click ⋮ at the top-right of the page. +3. Select ** Data** to open the Resource Data dialog window. +3. In the Resource Data window, click the **yaml** or **json** button to select the format. +4. Click the copy button at the top-right of the Resource Data window to copy the resource definition. + +This example shows how to view and copy the resource data for an event: + +{{< figure src="/images/go/view_manage_resources/view_event_data_web_ui_670.gif" alt="View an event's resource data in the web UI" link="/images/go/view_manage_resources/view_event_data_web_ui_670.gif" target="_blank" >}} + +### View resource data for a configuration resource + +To view and copy the YAML and JSON definitions for any configuration resource in the web UI: + +1. Open the individual resource page. +2. Click **RAW**. +3. In the resource data field, click the **yaml** or **json** button to select the format. +4. Click the copy button at the top-right of the resource data field to copy the resource definition. + +This example shows how to view and copy the resource data for an event filter: + +{{< figure src="/images/go/view_manage_resources/view_filter_data_web_ui_670.gif" alt="View an event filter's resource data in the web UI" link="/images/go/view_manage_resources/view_filter_data_web_ui_670.gif" target="_blank" >}} + + +[1]: ../#webui-homepage +[2]: ../bsm-module/ diff --git a/content/sensu-go/6.12/web-ui/webconfig-reference.md b/content/sensu-go/6.12/web-ui/webconfig-reference.md new file mode 100644 index 0000000000..db838bd95c --- /dev/null +++ b/content/sensu-go/6.12/web-ui/webconfig-reference.md @@ -0,0 +1,667 @@ +--- +title: "Web UI configuration reference" +linkTitle: "Web UI Configuration Reference" +reference_title: "Web UI configuration" +type: "reference" +description: "Sensu's web UI configuration feature allows you to customize your web UI displays. Read the reference to create and update web UI configurations." +weight: 150 +version: "6.12" +product: "Sensu Go" +menu: + sensu-go-6.12: + parent: web-ui +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access web UI configuration in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../commercial/). +{{% /notice %}} + +Web UI configuration allows you to define certain display options for the Sensu [web UI][3], such as which web UI theme to use, the number of items to list on each page, and which URLs and linked images to expand. +You can define a single custom web UI configuration to federate to all, some, or only one of your clusters. + +{{% notice note %}} +**NOTE**: Each cluster should have only one web configuration. +{{% /notice %}} + +## Web UI configuration example + +In this web UI configuration example: + +- Users will receive a customized sign-in message that is formatted with [Markdown][10] +- Details for the local cluster will not be displayed +- Each page will list 50 items (except the checks page, which will list 100 items) +- The web UI will use the classic theme +- The entities page will list only entities with the `proxy` subscription, in ascending order based on `last_seen` value +- The checks page will list checks alphabetically by name +- The web UI will begin to display the license expiration banner 45 days before the organization license expires +- Expanded links and images will be allowed for the listed URLs +- YAML will be the default format for [resource definitions in the web UI][9] + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: GlobalConfig +api_version: web/v1 +metadata: + name: custom-web-ui +spec: + signin_message: with your *LDAP or system credentials* + always_show_local_cluster: false + default_preferences: + poll_interval: 120000 + page_size: 50 + serialization_format: YAML + theme: classic + page_preferences: + - page: entities + page_size: 50 + order: LASTSEEN + selector: proxy in entity.subscriptions + - page: checks + page_size: 100 + order: NAME + license_expiry_reminder: 1080h0m0s + link_policy: + allow_list: true + urls: + - https://example.com + - steamapp://34234234 + - "//google.com" + - "//*.google.com" + - "//bob.local" + - https://grafana-host/render/metrics?width=500&height=250#sensu.io.graphic +{{< /code >}} + +{{< code json >}} +{ + "type": "GlobalConfig", + "api_version": "web/v1", + "metadata": { + "name": "custom-web-ui" + }, + "spec": { + "signin_message": "with your *LDAP or system credentials*", + "always_show_local_cluster": false, + "default_preferences": { + "poll_interval": 120000, + "page_size": 50, + "serialization_format": "YAML", + "theme": "classic" + }, + "page_preferences": [ + { + "page": "entities", + "page_size": 50, + "order": "LASTSEEN", + "selector": "proxy in entity.subscriptions" + }, + { + "page": "checks", + "page_size": 100, + "order": "NAME" + } + ], + "license_expiry_reminder": "1080h0m0s", + "link_policy": { + "allow_list": true, + "urls": [ + "https://example.com", + "steamapp://34234234", + "//google.com", + "//*.google.com", + "//bob.local", + "https://grafana-host/render/metrics?width=500&height=250#sensu.io.graphic" + ] + } + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Page preferences order values + +Available values for the `order` attribute in [page_preferences][11] vary depending on the page. + +Page | Order value and description +---- | --------------------------- +events | `ENTITY`: List events by the entities that created them, in ascending order by entity name

    `ENTITY_DESC`: List events by the entities that created them, in descending order by entity name

    `LASTOK`: List events by their last OK status, starting with the most recent

    `NEWEST`: List events by their timestamps, starting with the most recent

    `OLDEST`: List events by their timestamps, starting with the oldest

    `SEVERITY`: List events by their status, starting with the most severe +entities | `ID`: List entities by their IDs, in ascending order

    `ID_DESC`: List entities by their IDs, in descending order

    `LASTSEEN`: List entities by their `last_seen` timestamp, starting with the most recent +silences | `ID`: List silences by their IDs, in ascending order

    `ID_DESC`: List silences by their IDs, in descending order

    `BEGIN`: List silences by the time they begin, starting with the silence that begins soonest

    `BEGIN_DESC`: List silences by the time they begin, ending with the silence that begins first +checks | `NAME`: List checks by name, in alphabetical order

    `NAME_DESC`: List checks by name, in reverse alphabetical order +event-filters | `NAME`: List event filters by name, in alphabetical order

    `NAME_DESC`: List event filters by name, in reverse alphabetical order +handlers | `NAME`: List handlers by name, in alphabetical order

    `NAME_DESC`: List handlers by name, in reverse alphabetical order +mutators | `NAME`: List mutators by name, in alphabetical order

    `NAME_DESC`: List mutators by name, in reverse alphabetical order + +## Web UI configuration specification + +### Top-level attributes + +api_version | +-------------|------ +description | Top-level attribute that specifies the Sensu API group and version. For web UI configuration in this version of Sensu, the api_version should always be `web/v1`. +required | Required for web UI configuration in `wrapped-json` or `yaml` format. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +api_version: web/v1 +{{< /code >}} +{{< code json >}} +{ + "api_version": "web/v1" +} +{{< /code >}} +{{< /language-toggle >}} + +metadata | | +-------------|------ +description | Top-level scope that contains the web UI configuration's `name` and `created_by` information. +required | true +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +metadata: + name: custom-web-ui + created_by: admin +{{< /code >}} +{{< code json >}} +{ + "metadata": { + "name": "custom-web-ui", + "created_by": "admin" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +spec | +-------------|------ +description | Top-level map that includes web UI configuration [spec attributes][4]. +required | Required for web UI configuration in `wrapped-json` or `yaml` format. +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +spec: + signin_message: with your *LDAP or system credentials* + always_show_local_cluster: false + default_preferences: + poll_interval: 120000 + page_size: 50 + serialization_format: YAML + theme: classic + page_preferences: + - page: entities + page_size: 50 + order: LASTSEEN + selector: proxy in entity.subscriptions + - page: checks + page_size: 100 + order: NAME + license_expiry_reminder: 1080h0m0s + link_policy: + allow_list: true + urls: + - https://example.com + - steamapp://34234234 + - "//google.com" + - "//*.google.com" + - "//bob.local" + - https://grafana-host/render/metrics?width=500&height=250#sensu.io.graphic +{{< /code >}} +{{< code json >}} +{ + "spec": { + "signin_message": "with your *LDAP or system credentials*", + "always_show_local_cluster": false, + "default_preferences": { + "poll_interval": 120000, + "page_size": 50, + "serialization_format": "YAML", + "theme": "classic" + }, + "page_preferences": [ + { + "page": "entities", + "page_size": 50, + "order": "LASTSEEN", + "selector": "proxy in entity.subscriptions" + }, + { + "page": "checks", + "page_size": 100, + "order": "NAME" + } + ], + "license_expiry_reminder": "1080h0m0s", + "link_policy": { + "allow_list": true, + "urls": [ + "https://example.com", + "steamapp://34234234", + "//google.com", + "//*.google.com", + "//bob.local", + "https://grafana-host/render/metrics?width=500&height=250#sensu.io.graphic" + ] + } + } +} +{{< /code >}} +{{< /language-toggle >}} + +type | +-------------|------ +description | Top-level attribute that specifies the resource type. For web UI configuration, the type should always be `GlobalConfig`. +required | Required for web UI configuration in `wrapped-json` or `yaml` format. +type | String +example | {{< language-toggle >}} +{{< code yml >}} +type: GlobalConfig +{{< /code >}} +{{< code json >}} +{ + "type": "GlobalConfig" +} +{{< /code >}} +{{< /language-toggle >}} + +### Metadata attributes + +| created_by | | +-------------|------ +description | Username of the Sensu user who created or last updated the web UI configuration. Sensu automatically populates the `created_by` field when the web UI configuration is created or updated. The admin user, cluster admins, and any user with access to the [`GlobalConfig`][2] resource can create and update web UI configurations. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +created_by: admin +{{< /code >}} +{{< code json >}} +{ + "created_by": "admin" +} +{{< /code >}} +{{< /language-toggle >}} + +name | | +-------------|------ +description | Name for the web UI configuration that is used internally by Sensu. +required | true +type | String +example | {{< language-toggle >}} +{{< code yml >}} +name: custom-web-ui +{{< /code >}} +{{< code json >}} +{ + "name": "custom-web-ui" +} +{{< /code >}} +{{< /language-toggle >}} + +### Spec attributes + + + +always_show_local_cluster | +-------------|------ +description | Use only in federated environments. Set to `true` to display the cluster the user is currently connected to in the [namespace switcher][5]. To omit local cluster details, set to `false`. +required | false +type | Boolean +default | `false` +example | {{< language-toggle >}} +{{< code yml >}} +always_show_local_cluster: false +{{< /code >}} +{{< code json >}} +{ + "always_show_local_cluster": false +} +{{< /code >}} +{{< /language-toggle >}} + +default_preferences | +-------------|------ +description | Global [default preferences][1] page size and theme preferences for all users. +required | false +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +default_preferences: + poll_interval: 120000 + page_size: 50 + theme: classic +{{< /code >}} +{{< code json >}} +{ + "default_preferences": { + "poll_interval": 120000, + "page_size": 50, + "theme": "classic" + } +} +{{< /code >}} +{{< /language-toggle >}} + + + +license_expiry_reminder | +-------------|------ +description | Number of days before license expiration to begin displaying the [license expiration banner][12] in the web UI. The value must be a valid duration, such as `1080h`, `14400m`, or `24h59m59s`.{{% notice note %}} +**NOTE**: By default, the web UI displays the banner starting 30 days before license expiration. +{{% /notice %}} +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +license_expiry_reminder: 1080h0m0s +{{< /code >}} +{{< code json >}} +{ + "license_expiry_reminder": "1080h0m0s" +} +{{< /code >}} +{{< /language-toggle >}} + +link_policy | +-------------|------ +description | For labels or annotations that contain a URL, the policy for which domains are valid and invalid targets for conversion to a link or an image. +required | false +type | Map of key-value pairs +example | {{< language-toggle >}} +{{< code yml >}} +link_policy: + allow_list: true + urls: + - https://example.com + - steamapp://34234234 + - "//google.com" + - "//*.google.com" + - "//bob.local" + - https://grafana-host/render/metrics?width=500&height=250#sensu.io.graphic +{{< /code >}} +{{< code json >}} +{ + "link_policy": { + "allow_list": true, + "urls": [ + "https://example.com", + "steamapp://34234234", + "//google.com", + "//*.google.com", + "//bob.local", + "https://grafana-host/render/metrics?width=500&height=250#sensu.io.graphic" + ] + } +} +{{< /code >}} +{{< /language-toggle >}} + + + +page_preferences | +-------------|------ +description | [Page-specific preferences][6] for page size, order, and selector for all users. Any page preferences will override default preferences for the specified page. +required | false +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +page_preferences: + - page: entities + page_size: 50 + order: LASTSEEN + selector: proxy in entity.subscriptions + - page: checks + page_size: 100 + order: NAME +{{< /code >}} +{{< code json >}} +{ + "page_preferences": [ + { + "page": "entities", + "page_size": 50, + "order": "LASTSEEN", + "selector": "proxy in entity.subscriptions" + }, + { + "page": "checks", + "page_size": 100, + "order": "NAME" + } + ] +} +{{< /code >}} +{{< /language-toggle >}} + + + +signin_message | +-------------|------ +description | Custom message to display on the web UI sign-in modal. Accepts [Markdown][10] formatting. +required | false +type | String +default | `with your credentials` +example | {{< language-toggle >}} +{{< code yml >}} +signin_message: with your *LDAP or system credentials* +{{< /code >}} +{{< code json >}} +{ + "signin_message": "with your *LDAP or system credentials*" +} +{{< /code >}} +{{< /language-toggle >}} + +#### Default preferences attributes + +page_size | +-------------|------ +description | The number of items to list on each page. +required | false +type | Integer +default | `25` +example | {{< language-toggle >}} +{{< code yml >}} +page_size: 25 +{{< /code >}} +{{< code json >}} +{ + "page_size": 25 +} +{{< /code >}} +{{< /language-toggle >}} + +poll_interval | +-------------|------ +description | The frequency at which web UI pages will poll for new data from the Sensu backend. In milliseconds.

    Useful for increasing the polling interval duration if web UI sessions are causing heavy load. If you set the poll interval, all web UI views will use the poll interval value instead of their individual polling defaults.{{% notice note %}} +**NOTE**: If an individual user's settings conflict with the web UI configuration settings, Sensu will use the individual user's settings. +{{% /notice %}} +type | Integer +default | `10000` when page is visible. `300000` when page is not visible. +example | {{< language-toggle >}} +{{< code yml >}} +poll_interval: 120000 +{{< /code >}} +{{< code json >}} +{ + "poll_interval": 120000 +} +{{< /code >}} +{{< /language-toggle >}} + + + +serialization_format | +-------------|------ +description | Default format for [resource definitions in the web UI][9]. +required | false +type | String +default | `YAML` +allowed values | `JSON`, `YAML` +example | {{< language-toggle >}} +{{< code yml >}} +serialization_format: YAML +{{< /code >}} +{{< code json >}} +{ + "serialization_format": "YAML" +} +{{< /code >}} +{{< /language-toggle >}} + +theme | +---------------|------ +description | The theme used in the web UI.{{% notice note %}} +**NOTE**: If an individual user's settings conflict with the web UI configuration settings, Sensu will use the individual user's settings. +For example, if a user's system is set to dark mode and their web UI settings are configured to use their system settings, the web UI will use dark mode for that user, even if you set the theme to `classic` in your web UI configuration. +{{% /notice %}} +required | false +type | String +default | `sensu` +allowed values | `sensu`, `classic`, `uchiwa`, `tritanopia`, `deuteranopia` +example | {{< language-toggle >}} +{{< code yml >}} +theme: classic +{{< /code >}} +{{< code json >}} +{ + "theme": "classic" +} +{{< /code >}} +{{< /language-toggle >}} + +#### Page preferences attributes + +order | +-------------|------ +description | The order in which to list items on the specified page. Read [Page preferences order values][8] to learn more. +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +order: LASTSEEN +{{< /code >}} +{{< code json >}} +{ + "order": "LASTSEEN" +} +{{< /code >}} +{{< /language-toggle >}} + +page | +-------------|------ +description | The page to which the page preference settings apply. +required | true +type | String +allowed values | `events`, `entities`, `silences`, `checks`, `event-filters`, `handlers`, `mutators` +example | {{< language-toggle >}} +{{< code yml >}} +page: events +{{< /code >}} +{{< code json >}} +{ + "page": "events" +} +{{< /code >}} +{{< /language-toggle >}} + +page_size | +-------------|------ +description | The number of items to list for the specified page. +required | false +type | Integer +example | {{< language-toggle >}} +{{< code yml >}} +page_size: 100 +{{< /code >}} +{{< code json >}} +{ + "page_size": 100 +} +{{< /code >}} +{{< /language-toggle >}} + +selector | +-------------|------ +description | The [search expression][7] to apply to the specified page.
    {{% notice note %}} +**NOTE**: The selector page preference is not available for the events page. +{{% /notice %}} +required | false +type | String +example | {{< language-toggle >}} +{{< code yml >}} +selector: proxy in entity.subscriptions +{{< /code >}} +{{< code json >}} +{ + "selector": "proxy in entity.subscriptions" +} +{{< /code >}} +{{< /language-toggle >}} + +#### Link policy attributes + +allow_list | +-------------|------ +description | If the list of URLs acts as an allow list, `true`. If the list of URLs acts as a deny list, `false`. As an allow list, only matching URLs will be expanded. As a deny list, matching URLs will not be expanded, but any other URLs will be expanded. +required | false +type | Boolean +default | `false` +example | {{< language-toggle >}} +{{< code yml >}} +allow_list: true +{{< /code >}} +{{< code json >}} +{ + "allow_list": true +} +{{< /code >}} +{{< /language-toggle >}} + +urls | +-------------|------ +description | The list of URLs to use as an allow or deny list.
    {{% notice note %}}**NOTE**: For images from services that may not have an easily distinguishable file extension, append the anchor `#sensu.io.graphic` to the image URLs. +{{% /notice %}} +required | false +type | Array +example | {{< language-toggle >}} +{{< code yml >}} +urls: +- https://example.com +- steamapp://34234234 +- "//google.com" +- "//*.google.com" +- "//bob.local" +- https://grafana-host/render/metrics?width=500&height=250#sensu.io.graphic +{{< /code >}} +{{< code json >}} +{ + "urls": [ + "https://example.com", + "steamapp://34234234", + "//google.com", + "//*.google.com", + "//bob.local", + "https://grafana-host/render/metrics?width=500&height=250#sensu.io.graphic" + ] +} +{{< /code >}} +{{< /language-toggle >}} + + +[1]: #default-preferences-attributes +[2]: ../../api/enterprise/webconfig/ +[3]: ../ +[4]: #spec-attributes +[5]: ../view-manage-resources/#use-the-namespace-switcher +[6]: #page-preferences-attributes +[7]: ../search/ +[8]: #page-preferences-order-values +[9]: ../view-manage-resources/#view-resource-data-in-the-web-ui +[10]: https://www.markdownguide.org/ +[11]: #page-preferences-attribute +[12]: ../#license-expiration-banner diff --git a/content/sensu-go/6.12/web-ui/webconfig.md b/content/sensu-go/6.12/web-ui/webconfig.md new file mode 100644 index 0000000000..2407438e5e --- /dev/null +++ b/content/sensu-go/6.12/web-ui/webconfig.md @@ -0,0 +1,101 @@ +--- +title: "Configure the web UI" +linkTitle: "Configure the Web UI" +description: "Web UI configuration allows you to define certain display options for the Sensu web UI. Read this guide to configure customized displays for your Sensu web UI." +weight: 90 +version: "6.12" +product: "Sensu Go" +platformContent: false +menu: + sensu-go-6.12: + parent: web-ui +--- + +{{% notice commercial %}} +**COMMERCIAL FEATURE**: Access web UI configuration in the packaged Sensu Go distribution. +For more information, read [Get started with commercial features](../../commercial/). +{{% /notice %}} + +Web UI configuration allows you to define certain display options for the Sensu [web UI][3], such as which web UI theme to use, the number of items to list on each page, and which URLs and linked images to expand. +You can define a single custom web UI configuration to federate to all, some, or only one of your clusters. + +## Create a web UI configuration + +Use the [enterprise/web/v1 API POST endpoint][2] or [sensuctl create][5] to create a `GlobalConfig` resource. +The [web UI configuration reference][4] describes each attribute you can configure in the `GlobalConfig` resource. + +{{% notice note %}} +**NOTE**: Each cluster should have only one web configuration. +{{% /notice %}} + +If an individual user's settings conflict with the web UI configuration settings, Sensu will use the individual user's settings. +For example, if a user's system is set to dark mode and their web UI settings are configured to use their system settings, the web UI will use dark mode for that user, even if you set the theme to `classic` in your web UI configuration. + +## Federate a web UI configuration to specific clusters + +The web UI configuration in use is provided by the cluster you are connected to. +For example, if you open the web UI for https://cluster-a.sensu.my.org:3000, the web UI display will be configured according to the `GlobalConfig` resource for cluster-a. + +In a federated environment, you can create an [etcd replicator][6] for your `GlobalConfig` resource so you can use it for different clusters: + +{{< language-toggle >}} + +{{< code yml >}} +--- +type: EtcdReplicator +api_version: federation/v1 +metadata: + name: web_global_config +spec: + api_version: web/v1 + ca_cert: /path/to/ssl/trusted-certificate-authorities.pem + cert: /path/to/ssl/cert.pem + insecure: false + key: /path/to/ssl/key.pem + replication_interval_seconds: 120 + resource: GlobalConfig + url: "http://127.0.0.1:2379" +{{< /code >}} + +{{< code json >}} +{ + "type": "EtcdReplicator", + "api_version": "federation/v1", + "metadata": { + "name": "web_global_config" + }, + "spec": { + "api_version": "web/v1", + "ca_cert": "/path/to/ssl/trusted-certificate-authorities.pem", + "cert": "/path/to/ssl/cert.pem", + "insecure": false, + "key": "/path/to/ssl/key.pem", + "replication_interval_seconds": 120, + "resource": "GlobalConfig", + "url": "http://127.0.0.1:2379" + } +} +{{< /code >}} + +{{< /language-toggle >}} + +## Debugging in federated environments + +In a federated environment, a problem like incorrect configuration, an error, or a network issue could prevent a cluster from appearing in the web UI [namespace switcher][8]. + +If you set the [`always_show_local_cluster` attribute][7] to `true` in your web UI configuration, the namespace switcher will display a heading for each federated cluster, along with the local-cluster heading to indicate the cluster you are currently connected to. +With `always_show_local_cluster` set to `true`, the cluster administrator can directly connect to the local cluster even if there is a problem that would otherwise prevent the cluster from being listed in the namespace switcher. + +{{% notice note %}} +**NOTE**: Use the `always_show_local_cluster` attribute only in federated environments. +In a single-cluster environment, the namespace switcher will only list a local-cluster heading and the namespaces for that cluster. +{{% /notice %}} + + +[2]: ../../api/enterprise/webconfig/ +[3]: ../ +[4]: ../webconfig-reference/ +[5]: ../../sensuctl/create-manage-resources/#create-resources +[6]: ../../operations/deploy-sensu/etcdreplicators/ +[7]: ../webconfig-reference/#show-local-cluster +[8]: ../view-manage-resources/#use-the-namespace-switcher diff --git a/layouts/partials/footer_js.html b/layouts/partials/footer_js.html index b1fcc54816..3fa6cf0541 100644 --- a/layouts/partials/footer_js.html +++ b/layouts/partials/footer_js.html @@ -204,7 +204,7 @@ {{ if isset .Page.Params "product" }} 'version:{{ .Page.Params.version }}' {{ else }} - 'version:6.11', + 'version:6.12', 'version:1.0', 'version:2.16', 'version:1.9', diff --git a/layouts/partials/head.html b/layouts/partials/head.html index 5f3f6a3bbc..c5fcb46338 100644 --- a/layouts/partials/head.html +++ b/layouts/partials/head.html @@ -34,7 +34,7 @@ {{ end}} - {{ if not (eq .Params.version "6.11") }} + {{ if not (eq .Params.version "6.12") }} {{ end }} diff --git a/static.json b/static.json index c04e49ed2b..6fead640dc 100644 --- a/static.json +++ b/static.json @@ -39,11 +39,11 @@ "url": "/sensu-go/latest/operations/control-access/create-read-only-user", "status": 301 }, - "~ ^/sensu-go/6.11/?((?<=\/).*)?$": { + "~ ^/sensu-go/6.12/?((?<=\/).*)?$": { "url": "/sensu-go/latest/$1", "status": 302 }, - "~ ^/sensu-go/6.[0-7]/?((?<=\/).*)?$": { + "~ ^/sensu-go/6.[0-8]/?((?<=\/).*)?$": { "url": "/sensu-go/latest/$1", "status": 301 },