kibana-connectors

Kibana 连接器

核心概念

连接器用于存储 Elastic 服务和第三方系统的连接信息。满足规则条件时，告警规则会使用连接器来路由操作（通知）。连接器按 Kibana Space 管理，并可在该空间内的所有规则之间共享。

连接器类别

类别	连接器类型
大模型提供商	OpenAI、Google Gemini、Amazon Bedrock、Elastic Managed LLMs、AI Connector、MCP（预览版，9.3+）
事件管理	PagerDuty、Opsgenie、ServiceNow（ITSM、SecOps、ITOM）、Jira、Jira Service Management（9.2+）、IBM Resilient、Swimlane、Torq、Tines、D3 Security、XSOAR（9.1+）、TheHive
终端安全	CrowdStrike、SentinelOne、Microsoft Defender for Endpoint
消息传递	Slack（API / Webhook）、Microsoft Teams、Email
日志与可观测性	Server log、Index、Observability AI Assistant
Webhook	Webhook、Webhook - Case Management、xMatters
Elastic	Cases

身份验证

所有连接器 API 调用都需要 API 密钥身份验证或 Basic 身份验证。每个变更请求都必须包含 kbn-xsrf 标头。

kbn-xsrf: true

所需权限

对连接器的访问权限取决于你对启用告警功能的权限。你需要在 Stack Management 中拥有 Actions 和 Connectors 的 all 权限。

API 参考

基础路径：<kibana_url>/api/actions（非默认空间使用 /s/<space_id>/api/actions）。

操作	方法	端点
创建连接器	POST	/api/actions/connector/{id}
更新连接器	PUT	/api/actions/connector/{id}
获取连接器	GET	/api/actions/connector/{id}
删除连接器	DELETE	/api/actions/connector/{id}
获取所有连接器	GET	/api/actions/connectors
获取连接器类型	GET	/api/actions/connector_types
运行连接器	POST	/api/actions/connector/{id}/_execute

创建连接器

必填字段

字段	类型	描述
name	string	连接器的显示名称
connector_type_id	string	连接器类型（例如，.slack、.email、.webhook、.pagerduty、.jira）
config	object	特定类型的配置（非机密设置）
secrets	object	特定类型的机密（API 密钥、密码、令牌）

示例：创建 Slack 连接器（Webhook）

curl -X POST "https://my-kibana:5601/api/actions/connector/my-slack-connector" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey <your-api-key>" \
  -d '{
    "name": "Production Slack Alerts",
    "connector_type_id": ".slack",
    "config": {},
    "secrets": {
      "webhookUrl": "https://hooks.slack.com/services/T00/B00/XXXX"
    }
  }'

所有连接器类型都使用相同的请求结构，只有 connector_type_id、config 和 secrets 不同。可用类型及其必需字段请参阅 常见连接器类型 ID 表格。

示例：创建 PagerDuty 连接器

curl -X POST "https://my-kibana:5601/api/actions/connector/my-pagerduty" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey <your-api-key>" \
  -d '{
    "name": "PagerDuty Incidents",
    "connector_type_id": ".pagerduty",
    "config": {
      "apiUrl": "https://events.pagerduty.com/v2/enqueue"
    },
    "secrets": {
      "routingKey": "your-pagerduty-integration-key"
    }
  }'

更新连接器

PUT /api/actions/connector/{id} 会替换完整配置。connector_type_id 不可更改；如需更改，请先删除再重新创建。

列出和发现连接器

# Get all connectors in the current space
curl -X GET "https://my-kibana:5601/api/actions/connectors" \
  -H "Authorization: ApiKey <your-api-key>"

# Get available connector types
curl -X GET "https://my-kibana:5601/api/actions/connector_types" \
  -H "Authorization: ApiKey <your-api-key>"

# Filter connector types by feature (e.g., only those supporting alerting)
curl -X GET "https://my-kibana:5601/api/actions/connector_types?feature_id=alerting" \
  -H "Authorization: ApiKey <your-api-key>"

GET /api/actions/connectors 的响应包含 referenced_by_count，显示每个连接器被多少条规则使用。删除前务必检查此值。

运行连接器（测试）

直接执行连接器操作，可用于测试连接性。

curl -X POST "https://my-kibana:5601/api/actions/connector/my-slack-connector/_execute" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey <your-api-key>" \
  -d '{
    "params": {
      "message": "Test alert from API"
    }
  }'

删除连接器

curl -X DELETE "https://my-kibana:5601/api/actions/connector/my-slack-connector" \
  -H "kbn-xsrf: true" \
  -H "Authorization: ApiKey <your-api-key>"

警告： 删除被规则引用的连接器会导致这些规则操作静默失败。请先检查 referenced_by_count。

Terraform 提供程序

使用 elasticstack 提供程序资源 elasticstack_kibana_action_connector。

terraform {
  required_providers {
    elasticstack = {
      source  = "elastic/elasticstack"
    }
  }
}

provider "elasticstack" {
  kibana {
    endpoints = ["https://my-kibana:5601"]
    api_key   = var.kibana_api_key
  }
}

resource "elasticstack_kibana_action_connector" "slack" {
  name              = "Production Slack Alerts"
  connector_type_id = ".slack"

  config = jsonencode({})

  secrets = jsonencode({
    webhookUrl = "https://hooks.slack.com/services/T00/B00/XXXX"
  })
}

resource "elasticstack_kibana_action_connector" "index" {
  name              = "Alert Index Writer"
  connector_type_id = ".index"

  config = jsonencode({
    index              = "alert-history"
    executionTimeField = "@timestamp"
  })

  secrets = jsonencode({})
}

Terraform 要点：

• config 和 secrets 必须通过 jsonencode() 编码为 JSON 字符串
• 密钥会存储在 Terraform 状态中；请使用加密的远程后端，并限制状态文件的访问权限
• 导入现有连接器： terraform import elasticstack_kibana_action_connector.my_connector <space_id>/<connector_id>（默认空间请使用 default）
• 导入后，状态中不会填充密钥；必须在配置中提供这些密钥

预配置连接器（本地部署）

对于自我管理的 Kibana，可在 kibana.yml 中预配置连接器，使其在启动时即可用，无需手动创建：

xpack.actions.preconfigured:
  my-slack-connector:
    name: "Production Slack"
    actionTypeId: .slack
    secrets:
      webhookUrl: "https://hooks.slack.com/services/T00/B00/XXXX"
  my-webhook:
    name: "Custom Webhook"
    actionTypeId: .webhook
    config:
      url: "https://api.example.com/alerts"
      method: post
      hasAuth: true
    secrets:
      user: "alert-user"
      password: "secret-password"

无法通过 API 或 UI 编辑或删除预配置连接器。它们会显示 is_preconfigured: true，并且 API 响应中不包含 config 和 is_missing_secrets。

网络配置

通过 kibana.yml 自定义连接器网络（代理、TLS、证书）：

# Global proxy for all connectors
xpack.actions.proxyUrl: "https://proxy.example.com:8443"

# Per-host TLS settings
xpack.actions.customHostSettings:
  - url: "https://api.example.com"
    ssl:
      verificationMode: full
      certificateAuthoritiesFiles: ["/path/to/ca.pem"]

Kibana 工作流中的连接器

连接器是多个 Kibana 工作流的集成层，不仅用于告警通知：

工作流	连接器类型	关键模式
ITSM 工单处理	ServiceNow、Jira、IBM Resilient	告警处于活动状态时创建工单，在 Recovered 时关闭
值班升级	PagerDuty、Opsgenie	告警处于活动状态时执行 trigger，在 Recovered 时执行 resolve；始终设置去重键
案例管理	Cases（系统操作）	仅限 UI；将告警归入调查案例；可自动推送到 ITSM
消息传递 / 事件通知	Slack、Teams、Email	事件频道使用 onActionGroupChange；监控频道使用摘要
审计日志记录	Index	使用 onActiveAlert 将完整告警时间序列写入 Elasticsearch
AI 工作流	OpenAI、Bedrock、Gemini、AI Connector	为 Elastic AI Assistant 和 Attack Discovery 提供支持；由系统管理
自定义集成	Webhook	使用 Mustache 模板化 JSON 请求体发送通用 HTTP 出站请求

如需了解各工作流的详细模式、示例和决策指南，请参阅 workflows.md。

最佳实践

1. **在生产环境的本地部署中使用预配置连接器。**它们可避免密钥散落，能在导入 Saved Object 后继续使用，也不会被意外删除。动态场景或由用户管理的场景才使用通过 API 创建的连接器。

2. **将连接器关联到规则之前先进行测试。**使用 _execute 端点验证连接。配置错误的连接器会导致操作静默失败，只有在规则的执行历史记录中才能看到。

3. **删除前检查 referenced_by_count。**删除被活动规则使用的连接器会导致这些操作失败。列出连接器并确认其引用数为零，或先将规则重新分配给新的连接器。

4. 使用电子邮件域名允许列表。xpack.actions.email.domain_allowlist 设置会限制连接器可以发送邮件到哪些域名。如果更新此列表，收件人不在新列表中的现有电子邮件连接器将开始失败。

5. **在 Terraform 中保护密钥。**连接器密钥（API 密钥、密码、Webhook URL）会存储在 Terraform 状态中。使用加密的远程后端（S3+KMS、Azure Blob+encryption、GCS+CMEK），并限制对状态文件的访问。在变量上使用 sensitive = true。

6. **每项服务使用一个连接器，而非每条规则使用一个。**创建单个 Slack 连接器，并在多条规则中引用它。这样可以集中轮换密钥并减少重复。

7. **使用 Spaces 实现多租户隔离。**连接器的作用范围限定在 Kibana Space 内。为不同的团队或环境创建独立的空间，并在每个空间中配置连接器。

8. **监控连接器运行状况。**连接器执行失败会记录在事件日志索引（.kibana-event-log-*）中。连接器失败对 Task Manager 会显示为成功，但警报发送会静默失败。请查看 事件日志索引，了解实际失败率。

9. **始终在配置活动操作的同时配置恢复操作。**用于 ITSM 和值班工具（ServiceNow、Jira、PagerDuty、Opsgenie）的连接器支持关闭/解决操作。如果没有恢复操作，事件将永远保持打开状态。

10. **为值班连接器使用去重键。**将 dedupKey（PagerDuty）或 alias（Opsgenie）设为 {{rule.id}}-{{alert.id}}，确保解决事件恰好关闭正确的事件。否则，每次警报再次触发时都会创建一个新事件。

11. **调查工作流优先使用 Cases 连接器。**当警报需要通过评论、附件和指派人员进行调查时，请使用 Cases，而非直接使用 Jira/ServiceNow 连接器。Cases 提供原生调查 UI，也可以通过 Case 的外部连接推送到 ITSM。

12. **使用 Index 连接器创建持久的审计记录。**Index 连接器会写入 Elasticsearch，使警报历史记录可供搜索并用于仪表板。将其与目标索引上的 ILM 策略配合使用，以控制保留期限。

13. **通过 Action 设置限制连接器访问权限。**使用 xpack.actions.enabledActionTypes 仅允许组织需要的连接器类型，并使用 xpack.actions.allowedHosts 将出站连接限制到已知端点。

常见问题

1. 缺少 kbn-xsrf 标头。 所有 POST、PUT、DELETE 请求都需要 kbn-xsrf: true。如果省略此标头，将返回 400 错误。

2. connector_type_id 错误。 必须使用包含前导点号的准确字符串（例如 .slack，而不是 slack）。通过 GET /api/actions/connector_types 查询有效类型。

3. 必须提供空的 secrets 对象。 即使连接器没有密钥（例如 .index、.server-log），也必须在创建请求中提供 "secrets": {}。

4. 连接器类型不可更改。 创建后无法更改 connector_type_id。请删除并重新创建。

5. 导出／导入会丢失密钥。 通过 Saved Objects 导出连接器时，密钥会被移除。导入后，连接器会显示 is_missing_secrets: true，并且界面中会出现“修复”按钮。你必须手动或通过 API 重新输入密钥。

6. 无法通过 API 修改预配置连接器。 尝试更新或删除预配置连接器会返回 400。请仅在 kibana.yml 中管理它们。

7. 第三方服务的速率限制。 发送大量通知的连接器（例如每分钟针对每条告警发送一次通知）可能会触发 Slack、PagerDuty 或电子邮件服务提供商的速率限制。请使用告警摘要和规则侧的操作频率控制来减少通知量。

8. 连接器网络故障。 Kibana 必须能够访问连接器的目标 URL。请检查防火墙规则、代理设置和 DNS 解析。遇到 TLS 问题时，请使用 xpack.actions.customHostSettings。

9. 许可证要求。 某些连接器类型需要 Gold、Platinum 或 Enterprise 许可证。请检查 GET /api/actions/connector_types 返回的 minimum_license_required 字段。如果连接器的 enabled_in_config: true，但 enabled_in_license: false，则无法使用。

10. Terraform 导入不会恢复密钥。 将现有连接器导入 Terraform 时，无法从 Kibana 读取密钥。你必须在 Terraform 配置中提供这些密钥，否则下一次 terraform apply 会将它们覆盖为空值。

常见连接器类型 ID

类型 ID	名称	许可证
.email	电子邮件	Gold
.slack	Slack（Webhook）	Gold
.slack_api	Slack（API）	Gold
.pagerduty	PagerDuty	Gold
.jira	Jira	Gold
.servicenow	ServiceNow ITSM	Platinum
.servicenow-sir	ServiceNow SecOps	Platinum
.servicenow-itom	ServiceNow ITOM	Platinum
.webhook	Webhook	Gold
.index	索引	Basic
.server-log	服务日志	Basic
.opsgenie	Opsgenie	Gold
.teams	Microsoft Teams	Gold
.gen-ai	OpenAI	Enterprise
.bedrock	Amazon Bedrock	Enterprise
.gemini	Google Gemini	Enterprise
.cases	案例	Platinum
.crowdstrike	CrowdStrike	Enterprise
.sentinelone	SentinelOne	Enterprise
.microsoft_defender_endpoint	Microsoft Defender for Endpoint	Enterprise
.thehive	TheHive	Gold

注意： 使用 GET /api/actions/connector_types 可发现部署中所有可用类型及其准确的 minimum_license_required 值。XSOAR、Jira Service Management 和 MCP 的连接器类型已提供，但可能不会显示在较旧版本的 API 规范中。

示例

创建 Slack 连接器：“为我们的告警设置 Slack 通知。”使用 POST /api/actions/connector，并设置 connector_type_id: ".slack" 和 secrets.webhookUrl。在规则操作中使用返回的连接器 id。

将连接器添加到规则前进行测试：“验证 PagerDuty 连接器是否正常工作。” 使用 POST /api/actions/connector/{id}/_execute 和最精简的 params 对象确认连接正常，然后再将其添加到任何 规则中。

删除前审计连接器的使用情况：“移除旧的电子邮件连接器。”使用 GET /api/actions/connectors，检查 referenced_by_count — 如果非零，请先重新分配引用它的规则，然后再执行 DELETE /api/actions/connector/{id}。

指南

• 每个 POST、PUT 和 DELETE 请求都要包含 kbn-xsrf: true；省略时会返回 400。
• connector_type_id 不可变 — 要更改连接器类型，请删除并重新创建。
• 即使连接器没有密钥（例如 .index、.server-log），也始终传入 "secrets": {}。
• 删除前检查 referenced_by_count；删除连接器会导致所有引用它的规则操作无提示地失效。
• 连接器按空间划分；对于非默认 Kibana 空间，请在路径前加上 /s/<space_id>/api/actions/。
• 密钥仅可写入：GET 不会返回密钥，Saved Object 导出/导入时也会移除密钥；导入后务必重新提供。
• 将每个新连接器添加到规则前，都要使用 _execute 进行测试；生产环境中的连接器故障不会发出提示。

附加资源

• Kibana 连接器 API 参考
• 连接器概览
• 预配置连接器
• 告警设置（操作配置）
• Terraform：elasticstack_kibana_action_connector
• Terraform：管理 Kibana 规则和连接器资源