AlertChannel API Reference

Overview

The AlertChannel is a cluster-scoped Custom Resource that defines alert notification destinations. It supports Slack, PagerDuty, generic webhooks, and email. API Group: guardian.illenium.net/v1alpha1 Kind: AlertChannel Scope: Cluster (not namespaced)

Basic Examples

Slack Channel

apiVersion: guardian.illenium.net/v1alpha1
kind: AlertChannel
metadata:
  name: slack-alerts
spec:
  type: slack
  slack:
    webhookSecretRef:
      name: slack-webhook
      namespace: cronjob-guardian
      key: url
    defaultChannel: "#alerts"
  rateLimiting:
    maxAlertsPerHour: 100
    burstLimit: 10

PagerDuty Channel

apiVersion: guardian.illenium.net/v1alpha1
kind: AlertChannel
metadata:
  name: pagerduty-critical
spec:
  type: pagerduty
  pagerduty:
    routingKeySecretRef:
      name: pagerduty-key
      namespace: cronjob-guardian
      key: routing-key
    severity: critical

Spec Fields

type

string

required

Type of alert channel.Validation: Enum slack, pagerduty, webhook, email

slack

object

Slack configuration. Required when type is slack.

Show properties

webhookSecretRef

object

required

References the Secret containing the Slack webhook URL.

Show properties

name

string

required

Secret name.

namespace

string

required

Secret namespace.

key

string

required

Key within the Secret containing the webhook URL.

Secret Example:

apiVersion: v1
kind: Secret
metadata:
  name: slack-webhook
  namespace: cronjob-guardian
stringData:
  url: https://hooks.slack.com/services/YOUR/WEBHOOK/URL

defaultChannel

string

Overrides the webhook’s default channel. Use Slack channel format (e.g., "#alerts" or "@username").

messageTemplate

string

Go template for custom message formatting. Available template variables:

{\{.Type}\} - Alert type
{\{.Severity}\} - Alert severity
{\{.Message}\} - Alert message
{\{.CronJobName}\} - CronJob name
{\{.Namespace}\} - Namespace
{\{.Context}\} - Additional context

If not specified, uses the default Slack message format.

pagerduty

object

PagerDuty configuration. Required when type is pagerduty.

Show properties

routingKeySecretRef

object

required

References the Secret containing the PagerDuty Events API v2 routing key (also called integration key).

Show properties

name

string

required

Secret name.

namespace

string

required

Secret namespace.

key

string

required

Key within the Secret containing the routing key.

Secret Example:

apiVersion: v1
kind: Secret
metadata:
  name: pagerduty-key
  namespace: cronjob-guardian
stringData:
  routing-key: your-pagerduty-integration-key

severity

string

Default PagerDuty severity for alerts.Validation: Enum critical, error, warning, infoMaps Guardian severities to PagerDuty:

Guardian critical → PagerDuty critical
Guardian warning → PagerDuty warning

webhook

object

Generic webhook configuration. Required when type is webhook.

Show properties

urlSecretRef

object

required

References the Secret containing the webhook URL.

Show properties

name

string

required

Secret name.

namespace

string

required

Secret namespace.

key

string

required

Key within the Secret containing the URL.

Secret Example:

apiVersion: v1
kind: Secret
metadata:
  name: webhook-url
  namespace: cronjob-guardian
stringData:
  url: https://your-webhook-endpoint.com/alerts

method

string

default:"POST"

HTTP method for the webhook request.Validation: Enum POST, PUT

headers

map[string]string

Custom HTTP headers to include in webhook requests.

headers:
  Content-Type: application/json
  X-Custom-Header: guardian
  Authorization: Bearer ${TOKEN}

payloadTemplate

string

Go template for custom JSON payload formatting. Available template variables:

{\{.Type}\} - Alert type
{\{.Severity}\} - Alert severity
{\{.Message}\} - Alert message
{\{.CronJobName}\} - CronJob name
{\{.Namespace}\} - Namespace
{\{.Timestamp}\} - Alert timestamp
{\{.Context}\} - Additional context

Example:

payloadTemplate: |
  {
    "alert_type": "{\{.Type}\}",
    "severity": "{\{.Severity}\}",
    "message": "{\{.Message}\}",
    "cronjob": "{\{.Namespace}\}/{\{.CronJobName}\}",
    "timestamp": "{\{.Timestamp}\}"
  }

If not specified, uses the default webhook payload format.

email

object

Email configuration. Required when type is email.

Show properties

smtpSecretRef

object

required

References the Secret containing SMTP configuration.

Show properties

name

string

required

Secret name.

namespace

string

required

Secret namespace.

Secret Example: The Secret must contain these keys:

host - SMTP server hostname
port - SMTP server port (e.g., “587” for TLS)
username - SMTP username
password - SMTP password

apiVersion: v1
kind: Secret
metadata:
  name: smtp-credentials
  namespace: cronjob-guardian
stringData:
  host: smtp.gmail.com
  port: "587"
  username: [email protected]
  password: your-app-password

from

string

required

Sender email address.Example: "[email protected]"

array

required

List of recipient email addresses.

to:
  - [email protected]
  - [email protected]

subjectTemplate

string

Go template for email subject. Available template variables:

{\{.Type}\} - Alert type
{\{.Severity}\} - Alert severity
{\{.CronJobName}\} - CronJob name
{\{.Namespace}\} - Namespace

Default: "[{\{.Severity | upper}\}] CronJob Alert: {\{.Namespace}\}/{\{.CronJobName}\}"

bodyTemplate

string

Go template for email body (supports plain text or HTML). Available template variables:

{\{.Type}\} - Alert type
{\{.Severity}\} - Alert severity
{\{.Message}\} - Alert message
{\{.CronJobName}\} - CronJob name
{\{.Namespace}\} - Namespace
{\{.Timestamp}\} - Alert timestamp
{\{.Context}\} - Additional context

If not specified, uses the default email body format.

rateLimiting

object

Prevents alert storms by rate limiting notifications.

Show properties

maxAlertsPerHour

integer

default:"100"

Maximum number of alerts this channel can send per hour.Validation: Minimum value is 1

burstLimit

integer

default:"10"

Maximum number of alerts that can be sent in a short burst (per minute).Validation: Minimum value is 1

rateLimiting:
  maxAlertsPerHour: 50
  burstLimit: 5

testOnSave

boolean

default:"false"

Sends a test alert when the AlertChannel is created or updated. Useful for validating configuration.The test result will be reflected in the status.lastTestResult field.

Status Fields

The status subresource provides operational metrics and health information.

ready

boolean

Indicates whether the channel is operational and can send alerts.

lastTestTime

timestamp

When the channel was last tested (via testOnSave or manual testing).

lastTestResult

string

Result of the last test.Values: success, failed

lastTestError

string

Error message from the last failed test.

alertsSentTotal

integer

Cumulative count of alerts successfully sent via this channel.

lastAlertTime

timestamp

When the last alert was successfully sent.

alertsFailedTotal

integer

Cumulative count of alerts that failed to send via this channel.

lastFailedTime

timestamp

When the last alert send failure occurred.

lastFailedError

string

Error message from the last failed send attempt.

consecutiveFailures

integer

Number of consecutive failed send attempts. Resets to 0 on successful send.High values may indicate channel configuration issues or external service outages.

conditions

array

Standard Kubernetes condition array. Common condition types:

Ready: Channel is operational and can send alerts
ConfigValid: Channel configuration is valid
SecretFound: Referenced secrets exist and are readable

Complete Examples

Slack with Custom Template

apiVersion: guardian.illenium.net/v1alpha1
kind: AlertChannel
metadata:
  name: slack-custom
spec:
  type: slack
  slack:
    webhookSecretRef:
      name: slack-webhook
      namespace: cronjob-guardian
      key: url
    defaultChannel: "#cronjob-alerts"
    messageTemplate: |
      :{\{if eq .Severity "critical"}\}rotating_light{\{else}\}warning{\{end}\}: *{\{.Type}\}*
      
      *CronJob:* `{\{.Namespace}\}/{\{.CronJobName}\}`
      *Severity:* {\{.Severity | upper}\}
      *Message:* {\{.Message}\}
      {\{if .Context.SuggestedFix}\}
      
      *Suggested Fix:* {\{.Context.SuggestedFix}\}{\{end}\}
  rateLimiting:
    maxAlertsPerHour: 200
    burstLimit: 20
  testOnSave: true

Webhook with Authentication

apiVersion: guardian.illenium.net/v1alpha1
kind: AlertChannel
metadata:
  name: webhook-authenticated
spec:
  type: webhook
  webhook:
    urlSecretRef:
      name: webhook-config
      namespace: cronjob-guardian
      key: url
    method: POST
    headers:
      Content-Type: application/json
      Authorization: Bearer ${WEBHOOK_TOKEN}
      X-Source: cronjob-guardian
    payloadTemplate: |
      {
        "event_type": "cronjob_alert",
        "severity": "{\{.Severity}\}",
        "alert": {
          "type": "{\{.Type}\}",
          "message": "{\{.Message}\}",
          "cronjob": {
            "name": "{\{.CronJobName}\}",
            "namespace": "{\{.Namespace}\}"
          },
          "timestamp": "{\{.Timestamp}\}"
        }
      }
  rateLimiting:
    maxAlertsPerHour: 100
    burstLimit: 10

Email with HTML Template

apiVersion: guardian.illenium.net/v1alpha1
kind: AlertChannel
metadata:
  name: email-html
spec:
  type: email
  email:
    smtpSecretRef:
      name: smtp-credentials
      namespace: cronjob-guardian
    from: [email protected]
    to:
      - [email protected]
      - [email protected]
    subjectTemplate: "[{\{.Severity | upper}\}] {\{.Type}\} - {\{.Namespace}\}/{\{.CronJobName}\}"
    bodyTemplate: |
      <html>
      <body>
        <h2 style="color: {\{if eq .Severity "critical"}\}red{\{else}\}orange{\{end}\};">
          {\{.Type}\}
        </h2>
        <p><strong>CronJob:</strong> {\{.Namespace}\}/{\{.CronJobName}\}</p>
        <p><strong>Severity:</strong> {\{.Severity | upper}\}</p>
        <p><strong>Message:</strong> {\{.Message}\}</p>
        <p><strong>Time:</strong> {\{.Timestamp}\}</p>
        {\{if .Context.SuggestedFix}\}
        <hr>
        <h3>Suggested Fix</h3>
        <p>{\{.Context.SuggestedFix}\}</p>
        {\{end}\}
      </body>
      </html>
  rateLimiting:
    maxAlertsPerHour: 50
    burstLimit: 5
  testOnSave: true

Referencing AlertChannels

AlertChannels are referenced in CronJobMonitor resources:

apiVersion: guardian.illenium.net/v1alpha1
kind: CronJobMonitor
metadata:
  name: production-jobs
  namespace: production
spec:
  alerting:
    enabled: true
    channelRefs:
      - name: pagerduty-critical
        severities: [critical]
      - name: slack-alerts
        severities: [critical, warning]
      - name: email-team

Custom Resources

Configuration

Overview

Basic Examples

Slack Channel

PagerDuty Channel

Spec Fields

type

slack

pagerduty

webhook

email

rateLimiting

testOnSave

Status Fields

Complete Examples

Slack with Custom Template

Webhook with Authentication

Email with HTML Template

Referencing AlertChannels

Build docs developers (and LLMs) love

Custom Resources

Configuration

​Overview

​Basic Examples

​Slack Channel

​PagerDuty Channel

​Spec Fields

​type

​slack

​pagerduty

​webhook

​email

​rateLimiting

​testOnSave

​Status Fields

​Complete Examples

​Slack with Custom Template

​Webhook with Authentication

​Email with HTML Template

​Referencing AlertChannels

Build docs developers (and LLMs) love

Overview

Basic Examples

Slack Channel

PagerDuty Channel

Spec Fields

type

slack

pagerduty

webhook

email

rateLimiting

testOnSave

Status Fields

Complete Examples

Slack with Custom Template

Webhook with Authentication

Email with HTML Template

Referencing AlertChannels