Design Spec: elasticsearch-generic-log-query
Parent: #95
Target: rw-cli-codecollection
Spec
# CodeBundle Design Spec — Issue #95 intake
codebundle_name: "elasticsearch-generic-log-query"
target_collection: "rw-cli-codecollection"
display_name: "Elasticsearch Generic Log Search"
author: "rw-codebundle-agent"
purpose: |
Run configurable Elasticsearch log searches against a user-supplied cluster
endpoint, with the connection target (base URL / instance) fully separated
from the search query body so operators can reuse the same query across
environments or swap endpoints without duplicating CodeBundle logic.
tasks:
- name: "Check Elasticsearch Endpoint Reachability"
description: "Verifies HTTP(S) reachability and optional auth to the configured base URL before executing searches."
script_name: "check-elasticsearch-endpoint.sh"
expected_issue_severity: [2, 3]
access_level: "read-only"
data_type: "logs-config"
- name: "Run Generic Log Search and Summarize Results"
description: "POSTs the user-supplied JSON query to the configured index or index pattern; surfaces hit counts and a bounded sample for the report."
script_name: "run-generic-log-search.sh"
expected_issue_severity: [1, 2]
access_level: "read-only"
data_type: "logs"
- name: "Evaluate Search Result Thresholds"
description: "Optionally compares hit counts or aggregation outputs against max/min thresholds and raises issues when breached."
script_name: "evaluate-search-thresholds.sh"
expected_issue_severity: [3, 4]
access_level: "read-only"
data_type: "logs"
scope:
level: "Resource"
qualifiers:
- ELASTICSEARCH_BASE_URL
- ELASTICSEARCH_INDEX_PATTERN
iteration_pattern: |
One SLX per configured Elasticsearch endpoint (workspace-level URL or
discovered workload). The base URL is the primary scope; index pattern and
query body remain independent user variables for dynamic runtime input.
resource_types:
- "elasticsearch_cluster"
generation_strategy: |
Manual or static template: users supply ELASTICSEARCH_BASE_URL and credentials
via workspace secrets. Optional future discovery from Kubernetes services
labeled as Elasticsearch HTTP endpoints; default is user-provided instance
plus templated search tasks.
env_vars:
- name: ELASTICSEARCH_BASE_URL
description: "Base URL for the Elasticsearch HTTP API, without path (e.g. https://es.example.com:9200). Separated from query inputs."
required: true
- name: ELASTICSEARCH_INDEX_PATTERN
description: "Index name or pattern passed to the Search API path (e.g. logs-* , filebeat-*)."
required: true
- name: ELASTICSEARCH_QUERY_BODY
description: "JSON request body for POST _search (query, size, sort, aggregations). Must not embed the instance URL."
required: true
- name: SEARCH_THRESHOLD_MAX_HITS
description: "Optional maximum hit count; exceeding raises an issue."
required: false
default: ""
- name: SEARCH_THRESHOLD_MIN_HITS
description: "Optional minimum hit count; falling below raises an issue."
required: false
default: ""
- name: REQUEST_TIMEOUT_SECONDS
description: "HTTP client timeout for search and health probes."
required: false
default: "60"
secrets:
- name: elasticsearch_credentials
description: "Optional credentials for Elasticsearch (basic auth username/password and/or API key)."
format: |
JSON or k/v: ELASTICSEARCH_USERNAME, ELASTICSEARCH_PASSWORD, and/or
ELASTICSEARCH_API_KEY for Authorization headers.
platform:
name: "elasticsearch"
cli_tools:
- "curl"
- "jq"
auth_methods:
- "Basic authentication"
- "Elasticsearch API key (Authorization: ApiKey)"
- "Unauthenticated clusters (lab only)"
api_docs: "https://www.elastic.co/guide/en/elasticsearch/reference/current/search-search.html"
related_bundles:
- name: "elasticsearch-health"
relationship: "complements"
notes: "Exists in rw-public-codecollection for cluster health; this bundle adds generic log search with instance URL split from query body."
- name: "curl-generic"
relationship: "complements"
notes: "rw-public-codecollection generic HTTP; this bundle is Elasticsearch-specific (_search semantics, index in path, ES auth patterns)."
test_scenarios:
- name: "reachable_cluster_no_issue"
description: "Endpoint reachable, query returns hits within optional thresholds."
expected_issues: 0
- name: "unreachable_endpoint"
description: "Base URL not reachable or returns non-success HTTP."
expected_issues: 1
expected_severities: [2]
- name: "threshold_breach"
description: "Hit count outside configured min/max window."
expected_issues: 1
expected_severities: [3]
notes: |
Implement POST ${ELASTICSEARCH_BASE_URL}/${ELASTICSEARCH_INDEX_PATTERN}/_search
with Content-Type: application/json and body from ELASTICSEARCH_QUERY_BODY.
Never interpolate the base URL into the query JSON. Support Elastic Cloud
and OSS distributions; keep scripts portable (bash + curl + jq). Add README
examples showing the same query body reused against two different
ELASTICSEARCH_BASE_URL values. Follow rw-cli-codecollection patterns
(runbook.robot, RW.Core.Import User Variable, RW.CLI.Run Bash File).
Design Spec: elasticsearch-generic-log-query
Parent: #95
Target:
rw-cli-codecollectionSpec