kibana-connectors

Kibana コネクター

コアコンセプト

コネクターには、Elastic サービスやサードパーティシステムへの接続情報が保存されます。アラートルールでは、ルールの条件が満たされたときに アクション（通知）をルーティングするためにコネクターを使用します。コネクターは Kibana Space ごとに管理され、そのスペース内のすべてのルールで共有できます。

コネクターのカテゴリ

カテゴリ	コネクターの種類
LLM プロバイダー	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 専用。アラートを調査用の Cases にまとめ、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. ルールごとではなく、サービスごとに 1 つのコネクターを使用してください。 Slack コネクターを 1 つ作成し、複数のルールから参照します。これにより、シークレットのローテーションを一元化し、重複を減らせます。

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 コネクターを優先してください。 アラートにコメント、添付ファイル、担当者を含む調査が必要な場合は、Jira／ServiceNow への直接接続ではなく Cases を使用してください。Cases ではネイティブの調査 UI を利用でき、ケースの外部接続を介して 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 と表示され、UI に「修正」ボタンが表示されます。シークレットは手動または API 経由で再入力する必要があります。

6. 事前設定されたコネクターは API 経由で変更できない。 事前設定されたコネクターを更新または削除しようとすると、400 が返されます。これらは kibana.yml でのみ管理してください。

7. サードパーティサービスのレート制限。 大量の通知を送信するコネクター（例：アラートごとに毎分 1 件送信する場合）は、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

Type 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

Note: GET /api/actions/connector_types を使って、デプロイ環境で利用可能なすべてのタイプと、正確な minimum_license_required の値を確認してください。XSOAR、Jira Service Management、MCP のコネクタータイプも利用できますが、古いバージョンの API 仕様には表示されない場合があります。

例

Slack コネクターを作成する：「アラート用の Slack 通知を設定してください。」connector_type_id: ".slack" と secrets.webhookUrl を指定して POST /api/actions/connector を実行します。返されたコネクターの id をルールアクションで使用します。

ルールに追加する前にコネクターをテストする：「PagerDuty コネクターが動作するか確認してください。」 最小限の params オブジェクトを指定して POST /api/actions/connector/{id}/_execute を実行し、ルールに追加する前に接続を確認します。

削除前にコネクターの使用状況を監査する：「古いメールコネクターを削除してください。」GET /api/actions/connectors を実行して referenced_by_count を確認します。0 以外の場合は、まず参照しているルールを再割り当てしてから、DELETE /api/actions/connector/{id} を実行します。

ガイドライン

• すべての POST、PUT、DELETE に kbn-xsrf: true を指定してください。省略すると 400 が返されます。
• connector_type_id は変更できません。コネクタータイプを変更するには、削除して再作成してください。
• シークレットがないコネクター（例：.index、.server-log）でも、必ず "secrets": {} を渡してください。
• 削除前に referenced_by_count を確認してください。コネクターを削除すると、参照しているすべてのルールアクションが通知なしに機能しなくなります。
• コネクターはスペース単位です。デフォルト以外の Kibana Spaces では、パスの先頭に /s/<space_id>/api/actions/ を付けてください。
• シークレットは書き込み専用です。GET では返されず、Saved Object のエクスポート／インポート時に除外されるため、インポート後は必ず再入力してください。
• 新しいコネクターはすべて、ルールに追加する前に _execute でテストしてください。本番環境でのコネクター障害は通知されません。

追加リソース

• Kibana コネクター API リファレンス
• コネクターの概要
• 事前設定済みコネクター
• アラート設定（アクション設定）
• Terraform：elasticstack_kibana_action_connector
• Terraform：Kibana ルールおよびコネクターリソースの管理