F5 Distributed Cloud

Connect HolmesGPT to F5 Distributed Cloud (XC) to investigate WAF security events, bot defense, HTTP request logs, and load balancer configuration. Query which applications are under attack, why requests are being blocked, and whether origin servers are healthy.

Prerequisites

• An F5 Distributed Cloud tenant (e.g. https://your-tenant.console.ves.volterra.io)
• An API token

Creating an API Token

1. Log in to your F5 Distributed Cloud Console
2. Navigate to Administration > Personal Management > Credentials
3. Click Add Credentials, select API Token as the credential type, and set an expiry date
4. Copy the generated token - you'll use it as the api_token in the configuration below

For detailed instructions, see the F5 Distributed Cloud Credentials documentation.

Important

API requests inherit the RBAC of the user that created the token. Create the token from a user with a read-only (monitor) role - HolmesGPT only needs read access.

To verify your token:

curl -s "https://<your-tenant>.console.ves.volterra.io/api/web/namespaces" \
  -H "Authorization: APIToken <your-api-token>"

You should receive a JSON response listing your namespaces.

Configuration

Holmes CLIHolmes Helm ChartRobusta Helm Chart

Add the following to ~/.holmes/config.yaml. Create the file if it doesn't exist:

toolsets:
  f5xc:
    enabled: true
    config:
      api_url: <your tenant URL>  # e.g. https://acmecorp.console.ves.volterra.io
      api_token: <your API token>

After making changes to your configuration, run:

holmes toolset refresh

To test, run:

holmes ask "Which of my applications had WAF security events in the last 24 hours?"

First, create a Kubernetes secret with your F5 XC API token:

kubectl create secret generic f5xc-credentials \
  --from-literal=api-token=your-f5xc-api-token \
  -n holmes

Namespace must match Holmes' deployment

Create the secret in the same namespace where Holmes runs. The -n holmes flag in the Holmes Helm tab and -n default in the Robusta Helm tab match each chart's documented defaults — adjust if you installed Holmes/Robusta into a different namespace. A secret in the wrong namespace silently resolves to an empty env var and authentication will fail with no clear error.

Then add to your Holmes Helm values:

additionalEnvVars:
  - name: F5XC_API_TOKEN
    valueFrom:
      secretKeyRef:
        name: f5xc-credentials
        key: api-token

toolsets:
  f5xc:
    enabled: true
    config:
      api_url: <your tenant URL>  # e.g. https://acmecorp.console.ves.volterra.io
      api_token: "{{ env.F5XC_API_TOKEN }}"

First, create a Kubernetes secret with your F5 XC API token:

kubectl create secret generic f5xc-credentials \
  --from-literal=api-token=your-f5xc-api-token \
  -n default

Namespace must match Holmes' deployment

Create the secret in the same namespace where Holmes runs. The -n holmes flag in the Holmes Helm tab and -n default in the Robusta Helm tab match each chart's documented defaults — adjust if you installed Holmes/Robusta into a different namespace. A secret in the wrong namespace silently resolves to an empty env var and authentication will fail with no clear error.

Then add to your Robusta Helm values:

holmes:
  additionalEnvVars:
    - name: F5XC_API_TOKEN
      valueFrom:
        secretKeyRef:
          name: f5xc-credentials
          key: api-token
  toolsets:
    f5xc:
      enabled: true
      config:
        api_url: <your tenant URL>  # e.g. https://acmecorp.console.ves.volterra.io
        api_token: "{{ env.F5XC_API_TOKEN }}"

Update your Helm values and run a Helm upgrade:

helm upgrade robusta robusta/robusta --values=generated_values.yaml --set clusterName=<YOUR_CLUSTER_NAME>

Optional Fields

Option	Default	Description
verify_ssl	true	Whether to verify SSL certificates when calling the F5 XC API
timeout_seconds	30	Timeout in seconds for F5 XC API requests
default_limit	100	Default maximum number of events/logs returned by query tools (capped at 500, the API's per-page maximum)

Multiple Instances

The F5 Distributed Cloud toolset can connect to more than one F5 Distributed Cloud instance. List each one under instances: with a unique name. Any config field set outside instances: becomes a default that every instance inherits, so shared settings only need to be written once.

toolsets:
  f5xc:
    enabled: true
    config:
      instances:
        - name: prod
          api_url: <your tenant URL>
          api_token: <your API token>
        - name: staging
          api_url: <your tenant URL>
          api_token: <your API token>

When more than one instance is configured, HolmesGPT automatically adds an instance parameter to every F5 Distributed Cloud tool (so it can pick which instance to query) and a f5xc_list_instances tool to list the configured instances. With a single instance — including the flat config without instances: — the tools are unchanged and fully backwards compatible.

See Multiple Instances for the full behaviour, including global defaults and health reporting.

Common Use Cases

Which of my applications had WAF security events in the last 24 hours?

Why are requests to app.example.com getting blocked?

Show me the top attacking IPs across all namespaces today

Are there 5xx errors on the checkout load balancer in the last hour?

Advanced: HTTP Connector Alternative

The built-in toolset covers the most common troubleshooting endpoints. If you need access to other parts of the F5 XC API (e.g. DNS zones, CDN, sites), you can use an HTTP connector instead of - or alongside - the built-in toolset:

toolsets:
  f5xc-api:
    type: http
    enabled: true
    config:
      endpoints:
        - hosts:
            - "https://*.console.ves.volterra.io"
          paths:
            - "/api/web/*"
            - "/api/config/*"
            - "/api/data/*"
          methods: ["GET", "POST"]  # POST is required for log/event query endpoints
          auth:
            type: header
            name: "Authorization"
            value: "APIToken {{ env.F5XC_API_TOKEN }}"
      verify_ssl: true
      timeout_seconds: 30
    llm_instructions: |
      ### F5 Distributed Cloud API
      The base URL is: {{ env.F5XC_TENANT_URL }}
      Key endpoints:
      - GET /api/web/namespaces - list namespaces
      - GET /api/config/namespaces/{namespace}/http_loadbalancers - list HTTP load balancers (add ?report_fields for full specs)
      - GET /api/config/namespaces/{namespace}/origin_pools - list origin pools
      - POST /api/data/namespaces/{namespace}/app_security/events - query WAF/bot/API security events.
        Body: {"namespace": "...", "query": "{sec_event_type=\"waf_sec_event\"}", "start_time": "<RFC3339>", "end_time": "<RFC3339>", "limit": 100, "sort": "DESCENDING", "aggs": {}}
      - POST /api/data/namespaces/{namespace}/access_logs - query HTTP request logs (same body; useful query labels: rsp_code_class, vh_name)
      IMPORTANT: the vh_name label is 'ves-io-http-loadbalancer-<lb-name>', not the plain load balancer name.
      The 'events'/'logs' arrays in responses contain JSON-encoded strings - parse them to read fields.

Set the environment variables before running HolmesGPT:

export F5XC_TENANT_URL="https://your-tenant.console.ves.volterra.io"
export F5XC_API_TOKEN="your-api-token"

Note that the HTTP connector exposes a single generic request tool; the built-in f5xc toolset provides curated tools with parameter validation, query-size limits, and better guidance for the LLM, so prefer it for the endpoints it covers.

Capabilities

Tool Name	Description
f5xc_list_namespaces	List all namespaces in the tenant
f5xc_list_http_load_balancers	List HTTP load balancers in a namespace, optionally with full specs (domains, routes, WAF policy)
f5xc_get_http_load_balancer	Get the full configuration of a single HTTP load balancer
f5xc_list_origin_pools	List origin pools (backend server groups), optionally with origin servers and health checks
f5xc_query_security_events	Query WAF, bot defense, API security and service policy events, per namespace or tenant-wide
f5xc_aggregate_security_events	Count security events by field (top attack types, attacking IPs, targeted apps)
f5xc_query_request_logs	Query HTTP request (access) logs with response codes, paths, and timing breakdowns