> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashduty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Scalr 变更集成

> 通过 Scalr Webhook 将 Terraform / OpenTofu Run 同步到 Flashduty On-call，作为变更事件与告警、故障关联。

<Tip>**版本要求**：此功能需要 On-call 标准版及以上订阅。[了解更多](https://flashcat.cloud/flashduty/price/)</Tip>

通过 Scalr 的 Webhook 将 Terraform / OpenTofu Run 同步到 Flashduty On-call。每一次 Run 对应一条 Flashduty 变更：Run 等待人工确认时创建变更，Apply 成功或出错时更新同一条变更。

<div className="hide">
  ## 在 Flashduty On-call

  ***

  1. 进入 Flashduty 控制台，选择 **集成中心 → 变更事件**
  2. 选择 **Scalr**，填写集成名称
  3. 如需把变更分派到指定协作空间，在集成的 **路由** 中按标签（例如 `environment`、`workspace`）配置规则
  4. 点击 **保存**，复制生成的 **推送地址**
</div>

## 在 Scalr 中配置

***

Webhook 在 Account 范围创建，再分配给 Environment；分配后，该 Environment 下所有 Workspace 的 Run 都会触发它。

<Steps>
  <Step title="创建 Webhook">
    在 Account 范围进入 **Integrations → Events Forwarding → Webhook**，创建 Webhook（也可以用 Scalr API 或 Terraform Provider 的 `scalr_webhook` 资源）：

    1. **URL**：粘贴 Flashduty 集成的完整推送地址
    2. **Events**：勾选 `run:completed`、`run:errored` 和 `run:needs_attention`
    3. **Secret key**：必填，可点击 **Generate** 生成，也可填写任意字符串。Scalr 用它对请求签名，Flashduty 通过推送地址中的 `integration_key` 鉴权，不校验签名
  </Step>

  <Step title="分配给 Environment">
    新建的 Webhook 默认开启 **Allow all current and future environments to have access to this webhook**，无需再分配。如需限定范围，在 Webhook 的 **Environments access** 页签关闭该开关，再选择需要接入的 Environment。
  </Step>
</Steps>

## 一条变更是什么

***

| Scalr 对象 | 变更标识（change\_key） | 说明 |
| - | - | - |
| Run | `run.id`，例如 `run-v0oe5ki1pnaptv123` | 同一个 Run 的所有推送更新同一条变更；同一 Workspace 的两次 Run 是两条变更 |

Scalr 只在三种时刻推送：Run 需要人工确认、Run 成功结束、Run 出错。取消 Run、或在确认步骤放弃（Discard）Run 不会推送任何内容，这样的 Run 变更会停留在 Planned（或根本不会创建）。因此变更没有 Ready、Processing 状态，最早出现的状态是 Planned（等待确认）或结束状态。自动 Apply 的 Run 只会在结束时产生一条记录。

## 状态映射

***

| 推送事件（event\_name） | Run 状态（run.status） | Flashduty 变更状态 |
| - | - | - |
| run:needs\_attention | 任意，例如 planned、policy\_override（等待确认或策略覆盖） | Planned |
| run:completed | applied | Done |
| run:errored | errored | Failed |

结束事件按 Run 状态映射：`applied` 为 Done，`errored` 为 Failed（结束事件若携带 `canceled` 或 `discarded` 状态则为 Canceled，但 Scalr 不会推送）。Done 和 Failed 是结束状态，Flashduty 会记录变更结束时间。

以下推送返回成功但不生成变更：Run 状态为 `planned_and_finished` 的结束事件（只做了 Plan 或没有资源变更，没有内容被应用），以及不属于 `run:` 系列的其他事件。

## 变更内容

***

| 字段 | 内容 |
| - | - |
| 标题 | `<Environment>/<Workspace>: run <run.id>` |
| 描述 | Run 的 message（触发原因） |
| 链接 | Scalr 中该 Run 的页面 |

标签可用于路由和在变更列表中筛选：

| 标签 | 说明 |
| - | - |
| `environment` | Environment 名称 |
| `environment_id` | Environment ID，例如 `env-u0b83rvjmsjk123` |
| `workspace` | Workspace 名称 |
| `workspace_id` | Workspace ID，例如 `ws-v0oapbepcjdj9d123` |
| `run_id` | Run ID |
| `run_status` | 最新推送中的 Run 状态 |
| `source` | Run 的触发来源，例如 `dashboard-workspace` |
| `actor_id` | 创建 Run 的用户 ID |

Run 的变量（`variables`）和用户邮箱不会记录。

## 常见问题

***

<AccordionGroup>
  <Accordion title="为什么没有收到变更？">
    * 确认 Webhook 已启用，并已分配给 Run 所在的 Environment
    * 确认勾选了 `run:completed`、`run:errored` 和 `run:needs_attention`
    * 在 Webhook 的 **Deliveries** 页签查看推送记录和 Flashduty 的响应，也可以从这里重新发送
    * 只做 Plan 的 Run（Dry run，没有内容被应用）成功时不会生成变更
  </Accordion>

  <Accordion title="Dry run（Plan）失败会生成变更吗？">
    会。Scalr 的推送内容不区分 Dry run 与 Apply Run，Plan 阶段出错的 Run 会以 `run:errored` 推送，Flashduty 记为 Failed 变更。可以用 `source` 标签辅助区分，例如 VCS 拉取请求触发的 Run。
  </Accordion>

  <Accordion title="重复推送会重复记录吗？">
    不会。同一 Run、同一状态、同一时间的事件只记录一次，从 **Deliveries** 重新发送不会新增记录。
  </Accordion>

  <Accordion title="推送返回 InvalidParameter 错误？">
    * `unsupported event-name` 或 `unsupported run.status`：收到了 Flashduty 尚未支持的事件或 Run 状态，请联系我们
    * `run.id is missing` 或 `event-name is missing`：推送内容不完整，请确认推送来自 Scalr 的 Webhook
  </Accordion>
</AccordionGroup>