chore: update Terraform reference: v0.10.0 notification config

config/navigation.json

@@ -515,7 +515,8 @@
                 "terraform-reference/resources/policy_attachment",
                 "terraform-reference/resources/service_account",
                 "terraform-reference/resources/service_account_api_key",
-                "terraform-reference/resources/control"
+                "terraform-reference/resources/control",
+                "terraform-reference/resources/notification_config"
               ]
             },
             {
@@ -528,7 +529,8 @@
                 "terraform-reference/data-sources/action",
                 "terraform-reference/data-sources/policy",
                 "terraform-reference/data-sources/service_account",
-                "terraform-reference/data-sources/control"
+                "terraform-reference/data-sources/control",
+                "terraform-reference/data-sources/notification_config"
               ]
             },
             {

terraform-reference/data-sources/action.mdx

@@ -47,4 +47,4 @@ output "action_environments" {
 - `environments` (List of String) List of environment names this action monitors.
 - `last_modified_at` (Number) Unix timestamp (with fractional seconds) of when the action was last modified.
 - `number` (Number) Server-assigned numeric identifier for the action.
-- `triggers` (List of String) List of trigger event types that activate this action.
+- `triggers` (List of String) List of trigger event types that activate this action. See the [`kosli_action` resource](/terraform-reference/resources/action#triggers) for what each trigger fires on.

terraform-reference/data-sources/notification_config.mdx

@@ -0,0 +1,67 @@
+---
+title: "kosli_notification_config data source"
+description: "Fetches where Kosli sends one type of notification that Kosli raises itself, and when that notification was last delivered."
+icon: "database"
+---
+
+Fetches where Kosli sends one type of notification that Kosli raises itself, and when that notification was last delivered.
+
+If the organization has not configured a type, the data source returns `configured = false` and empty target sets. In that case, Kosli derives the recipients from what the notification is about.
+
+Use this data source to:
+
+- Check whether the organization overrides the recipients Kosli derives
+- Read the configured email, Slack webhook, and webhook targets
+- Monitor when a notification was last delivered and whether the latest delivery failed
+
+## Example usage
+
+```terraform
+terraform {
+  required_providers {
+    kosli = {
+      source = "kosli-dev/kosli"
+    }
+  }
+}
+
+# Query where API key expiry warnings are sent
+data "kosli_notification_config" "api_key_expiry" {
+  notification_type = "api_key_expiry"
+}
+
+output "api_key_expiry_configured" {
+  description = "Whether the organization overrides the recipients Kosli derives"
+  value       = data.kosli_notification_config.api_key_expiry.configured
+}
+
+output "api_key_expiry_emails" {
+  description = "Email addresses API key expiry warnings are sent to"
+  value       = data.kosli_notification_config.api_key_expiry.emails
+}
+
+output "api_key_expiry_last_notified_at" {
+  description = "When an API key expiry warning was last sent (RFC3339)"
+  value       = data.kosli_notification_config.api_key_expiry.last_notified_at
+}
+```
+
+## Read-only access
+
+Data sources provide read-only access to notification configuration. To set or remove targets, use the [`kosli_notification_config` resource](/terraform-reference/resources/notification_config).
+
+## Schema
+
+### Required
+
+- `notification_type` (String) The type of notification to query. Currently `api_key_expiry` (warnings that a service account API key is about to expire).
+
+### Read-only
+
+- `configured` (Boolean) Whether the organization has configured targets for this notification type.
+- `emails` (Set of String) Email addresses the notification is sent to.
+- `last_failure_at` (String) When the most recent failed delivery happened (RFC3339). Null unless that failure is more recent than the last successful delivery.
+- `last_failure_error` (String) Why the most recent failed delivery failed. Null unless that failure is more recent than the last successful delivery.
+- `last_notified_at` (String) When a notification of this type was last sent for the organization (RFC3339). Null if none has been sent.
+- `slack_webhooks` (Set of String, Sensitive) Slack incoming webhook URLs the notification is posted to.
+- `webhooks` (Set of String, Sensitive) Generic webhook URLs the notification is POSTed to.

terraform-reference/resources/action.mdx

@@ -31,15 +31,41 @@ resource "kosli_action" "compliance_alerts" {
   webhook_url  = "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXX"
 }
 
-# Action that fires on scaling events
-resource "kosli_action" "scaling_alerts" {
-  name         = "scaling-alerts"
+# Action that fires when a running artifact becomes compliant or non-compliant,
+# or gains new provenance (UI: "Artifact changed")
+resource "kosli_action" "artifact_changed_alerts" {
+  name         = "artifact-changed-alerts"
   environments = ["staging-ecs"]
   triggers     = ["ON_SCALED_ARTIFACT"]
   webhook_url  = "https://outlook.office.com/webhook/XXXX"
 }
+
+# Action that fires on artifact lifecycle events in the environment
+resource "kosli_action" "artifact_lifecycle_alerts" {
+  name         = "artifact-lifecycle-alerts"
+  environments = ["staging-ecs"]
+  triggers     = ["ON_STARTED_ARTIFACT", "ON_EXITED_ARTIFACT", "ON_ALLOWED_ARTIFACT"]
+  webhook_url  = "https://outlook.office.com/webhook/XXXX"
+}
 ```
 
+## Triggers
+
+The `triggers` attribute must contain one or more of the following event types:
+
+| Value | Fires when |
+|---|---|
+| `ON_STARTED_ARTIFACT` | An artifact starts running in the environment |
+| `ON_EXITED_ARTIFACT` | An artifact stops running |
+| `ON_SCALED_ARTIFACT` | A running artifact becomes compliant or non-compliant, or gains new provenance (UI: "Artifact changed") |
+| `ON_ALLOWED_ARTIFACT` | An artifact is added to the allow-list |
+| `ON_COMPLIANT_ENV` | The environment becomes compliant |
+| `ON_NON_COMPLIANT_ENV` | The environment becomes non-compliant |
+
+<Note>
+`ON_SCALED_ARTIFACT` keeps its historical name for backwards compatibility. Kosli no longer records scaling events, so this trigger fires on artifact changes.
+</Note>
+
 ## Import
 
 Actions can be imported using their name:
@@ -55,7 +81,7 @@ terraform import kosli_action.compliance_alerts compliance-alerts
 
 - `environments` (List of String) List of environment names this action monitors.
 - `name` (String) Name of the action. Must be unique within the organization. Changing this will force recreation of the resource.
-- `triggers` (List of String) List of trigger event types that activate this action (e.g. `ON_NON_COMPLIANT_ENV`, `ON_COMPLIANT_ENV`).
+- `triggers` (List of String) List of trigger event types that activate this action. One or more of `ON_STARTED_ARTIFACT`, `ON_EXITED_ARTIFACT`, `ON_SCALED_ARTIFACT`, `ON_ALLOWED_ARTIFACT`, `ON_COMPLIANT_ENV`, `ON_NON_COMPLIANT_ENV`. See [Triggers](#triggers) for what each one fires on.
 - `webhook_url` (String, Sensitive) Webhook URL to send notifications to.
 
 ### Read-only

terraform-reference/resources/notification_config.mdx

@@ -0,0 +1,78 @@
+---
+title: "kosli_notification_config resource"
+description: "Manages where Kosli sends one type of notification that Kosli raises itself, such as API key expiry warnings."
+icon: "cube"
+---
+
+Manages where Kosli sends one type of notification that Kosli raises itself, such as API key expiry warnings. The configured targets replace the recipients Kosli would otherwise derive from what the notification is about.
+
+<Note>
+An organization has at most one configuration per `notification_type`. Creating this resource replaces any configuration already set for that type (for example, through the Kosli UI). Destroying it removes the configuration, so Kosli derives the recipients again. Requires a service account with **Admin** permissions.
+</Note>
+
+To read the current configuration and delivery status, use the [`kosli_notification_config` data source](/terraform-reference/data-sources/notification_config).
+
+## Example usage
+
+```terraform
+terraform {
+  required_providers {
+    kosli = {
+      source = "kosli-dev/kosli"
+    }
+  }
+}
+
+# Send API key expiry warnings to the platform team instead of the recipients
+# Kosli derives by default. Set at least one of emails, slack_webhooks or
+# webhooks; destroying the resource restores the derived recipients.
+resource "kosli_notification_config" "api_key_expiry" {
+  notification_type = "api_key_expiry"
+
+  emails = [
+    "platform-team@example.com",
+    "security@example.com",
+  ]
+
+  # Webhook URLs are secrets: in real configurations pass them in through a
+  # sensitive variable rather than committing them.
+  slack_webhooks = ["https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXX"]
+  webhooks       = ["https://ops.example.com/kosli/notifications"]
+}
+```
+
+## Notification types
+
+| Value | Notification |
+|---|---|
+| `api_key_expiry` | A service account API key is about to expire |
+
+## Targets
+
+Each target attribute takes one or more values. You must set at least one of them.
+
+- The provider sends every address in `emails` as a single email target.
+- The provider sends each URL in `slack_webhooks` or `webhooks` as its own target.
+- Kosli lowercases the host of webhook URLs and the domain of email addresses, and strips trailing slashes from URLs. When Kosli stores an equivalent value, the provider keeps the spelling from your configuration, so this normalization never shows up as a diff.
+- URL paths and email local parts are compared exactly.
+
+## Import
+
+Notification configs can be imported using their notification type:
+
+```shell
+# Import an existing notification config by its notification type
+terraform import kosli_notification_config.api_key_expiry api_key_expiry
+```
+
+## Schema
+
+### Required
+
+- `notification_type` (String) The type of notification to configure. Currently `api_key_expiry` (warnings that a service account API key is about to expire). Changing this will force recreation of the resource.
+
+### Optional
+
+- `emails` (Set of String) Email addresses the notification is sent to.
+- `slack_webhooks` (Set of String, Sensitive) Slack incoming webhook URLs the notification is posted to. Must use HTTPS.
+- `webhooks` (Set of String, Sensitive) Generic webhook URLs the notification is POSTed to as JSON (payload version `1.0`). Must use HTTPS.