Alerting

Configure Bifrost Enterprise alert channels, rules, history retention, and webhook network controls in Helm

Alerting is an enterprise-only feature and requires the enterprise Bifrost image.

Helm renders bifrost.alerting into the generated config.json that Bifrost loads at startup. Use this page when you want alert channels and rules managed from values files.

For the runtime behavior and UI workflow, see Alerting, Alert Rules, Alert Channels, and Alert History.

Alert rules evaluate governance metrics. Define the referenced virtual keys, teams, customers, budgets, and rate limits under bifrost.governance, or create them through the Web UI or API before the rule is evaluated.

---

Quick example

Create Kubernetes secrets for channel credentials and expose them as environment variables to the Bifrost pod:

kubectl create secret generic bifrost-alerting-secrets \
  --from-literal=slack-webhook-url='https://hooks.slack.com/services/T000/B000/XXXX' \
  --from-literal=teams-webhook-url='https://example.webhook.office.com/workflows/XXXX' \
  --from-literal=pagerduty-routing-key='pd-routing-key' \
  --from-literal=webhook-url='https://hooks.example.com/alerts' \
  --from-literal=webhook-token='secret-token'

Reference those values from your Helm values file:

env:
  - name: SLACK_WEBHOOK_URL
    valueFrom:
      secretKeyRef:
        name: bifrost-alerting-secrets
        key: slack-webhook-url
  - name: TEAMS_WEBHOOK_URL
    valueFrom:
      secretKeyRef:
        name: bifrost-alerting-secrets
        key: teams-webhook-url
  - name: PAGERDUTY_ROUTING_KEY
    valueFrom:
      secretKeyRef:
        name: bifrost-alerting-secrets
        key: pagerduty-routing-key
  - name: ALERT_WEBHOOK_URL
    valueFrom:
      secretKeyRef:
        name: bifrost-alerting-secrets
        key: webhook-url
  - name: ALERT_WEBHOOK_TOKEN
    valueFrom:
      secretKeyRef:
        name: bifrost-alerting-secrets
        key: webhook-token

bifrost:
  alerting:
    history_retention_days: 365
    evaluation_interval_seconds: 10
    webhook_network:
      allow_http: false
      allow_private_network: false

    channels:
      - id: "slack-platform"
        name: "Platform Slack"
        type: "slack"
        enabled: true
        config:
          webhook_url: "env.SLACK_WEBHOOK_URL"
        cooldown_seconds: 60

      - id: "pagerduty-prod"
        name: "Production PagerDuty"
        type: "pagerduty"
        enabled: true
        config:
          routing_key: "env.PAGERDUTY_ROUTING_KEY"

      - id: "ops-webhook"
        name: "Ops webhook"
        type: "webhook"
        enabled: true
        config:
          url: "env.ALERT_WEBHOOK_URL"
          headers:
            X-Alert-Token: "env.ALERT_WEBHOOK_TOKEN"

    rules:
      - id: "vk-budget-80"
        name: "Virtual key budget at 80%"
        enabled: true
        scope_type: "virtual_key"
        scope_id: "vk-platform"
        cel_expression: "budget_usage_percent >= 80.0"
        channel_ids: ["slack-platform"]
        cooldown_seconds: 300

      - id: "team-requests-90"
        name: "Team request limit at 90%"
        enabled: true
        scope_type: "team"
        scope_id: "team-platform"
        cel_expression: "rate_limit_request_usage_percent >= 90.0"
        channel_ids: ["slack-platform", "ops-webhook"]
        notify_once_per_reset_cycle: true

Apply the values:

helm upgrade bifrost bifrost/bifrost --reuse-values -f alerting-values.yaml

---

Top-level fields

Field	Type	Default	Description
bifrost.alerting.history_retention_days	integer	365	Days to retain alert history. Set 0 to disable retention pruning.
bifrost.alerting.evaluation_interval_seconds	integer	60	Seconds between rule evaluations. Use 5 to 10 for one-minute budget or rate-limit reset windows.
bifrost.alerting.webhook_network	object	See below	Outbound URL validation controls for webhook-based channels.
bifrost.alerting.channels	array	[]	Declarative notification destinations.
bifrost.alerting.rules	array	[]	Declarative CEL rules evaluated against governance metrics.

Alerting samples the current governance counters at this interval. Keep evaluation_interval_seconds comfortably below the shortest configured budget or rate-limit reset duration so a brief threshold breach is observed before governance resets the counter.

Webhook network controls

bifrost:
  alerting:
    webhook_network:
      allow_http: false
      allow_private_network: false

Field	Default	Description
allow_http	false	Allow Slack, Microsoft Teams, and generic webhook channels to use http:// URLs. PagerDuty always uses its fixed HTTPS endpoint.
allow_private_network	false	Allow webhook destinations on RFC1918 private networks. Link-local and unspecified addresses remain blocked.

Keep both webhook network controls disabled for production unless you are intentionally sending alerts to trusted internal endpoints. Enabling them weakens TLS and SSRF protections.

---

Channels

Each channel needs a stable id, a display name, a type, an enabled flag, and a type-specific config.

Field	Required	Description
id	Yes	Stable channel ID. Rules reference this ID in channel_ids.
name	Yes	Operator-facing channel name.
description	No	Optional description.
type	Yes	slack, microsoft_teams, pagerduty, or webhook.
enabled	Yes	Whether this channel can receive notifications.
cooldown_seconds	No	Minimum seconds between sends for this channel. Set 0 for no channel-level cooldown.
config	Conditional	Required for every supported channel type.

Channel config

Credential and endpoint fields support env.VAR_NAME references. Bifrost resolves the value from the pod environment at startup.

Channel type	Required config	Notes
slack	Exactly one of webhook_url or url	Slack incoming webhook URL.
microsoft_teams	Exactly one of webhook_url or url	Teams incoming webhook or Workflows URL.
pagerduty	Exactly one of routing_key or integration_key	PagerDuty Events API v2 integration key.
webhook	Exactly one of url or webhook_url	Generic webhook URL. Optional headers values also support env.VAR_NAME.

For each alias pair, provide exactly one key. For example, use either webhook_url or url for Slack, not both.

bifrost:
  alerting:
    channels:
      - id: "teams-ops"
        name: "Ops Teams"
        type: "microsoft_teams"
        enabled: true
        config:
          webhook_url: "env.TEAMS_WEBHOOK_URL"

      - id: "pagerduty-prod"
        name: "Production PagerDuty"
        type: "pagerduty"
        enabled: true
        config:
          routing_key: "env.PAGERDUTY_ROUTING_KEY"

---

Rules

Rules evaluate CEL expressions against governance metrics collected for a virtual key, team, or customer.

Field	Required	Description
id	Yes	Stable rule ID.
name	Yes	Operator-facing rule name.
description	No	Optional description.
enabled	Yes	Whether this rule is evaluated.
scope_type	Yes	virtual_key, team, or customer.
scope_id	Yes	ID of the scoped virtual key, team, or customer.
cel_expression	Yes	CEL expression that evaluates to a boolean.
query	No	Optional UI query-builder representation of cel_expression.
cooldown_seconds	No	Minimum seconds between notifications for this rule. Default is 60. Set 0 to disable rule-level cooldown.
notify_once_per_reset_cycle	No	When true, notify at most once per matched budget or rate-limit reset cycle.
channel_ids	Yes	One or more alert channel IDs.
target_type	Conditional	Use budget with target_id to evaluate one specific budget.
target_id	Conditional	Required when target_type is set.

Scopes and targets

Every rule must have a scope. A rule can either evaluate all budgets for that scope or target one budget explicitly.

Behavior	target_type	target_id
Evaluate all budgets in the scope	Omit	Omit
Evaluate one budget	budget	Budget ID

target_type and target_id must be provided together.

CEL examples

# Any budget in the scope reaches 80%
budget_usage_percent >= 80.0

# Request rate limit reaches 90%
rate_limit_request_usage_percent >= 90.0

# Either budget or token rate limit is exhausted
budget_usage_percent >= 100.0 || rate_limit_token_usage_percent >= 100.0

For the complete variable list, see Alerting CEL variables.

---

Specific budget example

Use target_type: "budget" and target_id when a rule should evaluate one budget instead of every budget in the scope.

bifrost:
  alerting:
    rules:
      - id: "vk-platform-monthly-budget-90"
        name: "Platform monthly budget at 90%"
        enabled: true
        scope_type: "virtual_key"
        scope_id: "vk-platform"
        target_type: "budget"
        target_id: "budget-platform-monthly"
        cel_expression: "budget_usage_percent >= 90.0"
        channel_ids: ["pagerduty-prod"]
        cooldown_seconds: 600

---

Reset-cycle notifications

Set notify_once_per_reset_cycle when you want one notification per budget or rate-limit reset window, instead of repeated sends based on a cooldown.

bifrost:
  alerting:
    rules:
      - id: "team-token-limit-cycle"
        name: "Team token limit per reset cycle"
        enabled: true
        scope_type: "team"
        scope_id: "team-platform"
        cel_expression: "rate_limit_token_usage_percent >= 90.0"
        channel_ids: ["slack-platform"]
        notify_once_per_reset_cycle: true

This is useful for rate limits and recurring budgets because the same condition can remain true until the reset window rolls over.

---

Clusters

In a Bifrost Enterprise cluster, only the leader evaluates alert rules and writes alert history. Followers can serve inference traffic and update shared governance usage, but they do not dispatch duplicate alerts.

No extra alerting configuration is required for cluster mode. Configure clustering separately under bifrost.cluster.

---

Validation

The Helm values schema validates alerting configuration during template rendering and install or upgrade operations. It checks channel types, required channel config, exact-one alias pairs, required channel_ids, and the target_type / target_id pairing.

helm template bifrost bifrost/bifrost -f alerting-values.yaml >/tmp/bifrost-rendered.yaml

---

Next steps

Alerting overview

Learn how alert evaluation, cooldowns, history, and clustering work.

Governance in Helm

Define the virtual keys, teams, customers, budgets, and rate limits that alert rules evaluate.