# Let a budget propose stopping resources

Give a budget an action, so that when its spend reaches a percentage it proposes stopping non-production instances and databases and scaling autoscaling groups to zero, for a person to approve or dismiss.

Nothing stops until someone approves. Replace _budget-id_ with the budget's id and _proposal-id_
with the proposal's.

## Prerequisites

- Permission for `billing:UpdateBudget` (or `billing:CreateBudget` for a new budget) to give a
  budget an action.
- `billing:ApproveBudgetAction` on the budget to approve or dismiss a proposal. The console enables
  its buttons only for someone who holds it on every budget (`rn:ews:de1:<organization
id>:billing:*`). Each stop also needs your own `ec2:StopInstances`, `rds:StopDBInstance` or
  `autoscaling:UpdateAutoScalingGroup` on that resource.
- `billing:GetBudgets` to see proposals and to open **Budgets**.

## Give a budget an action

An action is a threshold (`thresholdPercent`, default 100) and a selector: tag clauses that mean
non-production, all of which must match. The default selector is `environment` in `dev`,
`development`, `test`, `staging` or `preview`.

**Console**
1. Open **Budgets**, then choose **Create budget**, or the edit button of a budget.
2. Under **Suggest what to stop**, select the check box.
3. For **At (%)**, enter the threshold.
4. For **Non-production means**, keep the default or enter clauses as `key=value,value`, several
   separated by `;`.
5. Choose **Create budget** or **Save budget**.

**CLI**
```sh
dcloud billing budgets update budget-id \
  --action '{"thresholdPercent":100,"selector":[{"key":"environment","values":["dev","test","staging"]}]}'
```

**API**
```http
PATCH /billing/api/budgets/budget-id
{ "action": { "thresholdPercent": 100, "selector": [{ "key": "environment", "values": ["dev", "test", "staging"] }] } }
```

`"action": null` removes the action.

**Terraform**
```hcl
resource "dcloud_budget" "staging" {
  name         = "Staging"
  amount_cents = 20000
  period       = "monthly"
  action       = jsonencode({ thresholdPercent = 100, selector = [{ key = "environment", values = ["staging"] }] })
}
```

To see what the action would propose right now:

```sh
dcloud billing budgets action-preview budget-id
```

## What a proposal holds

When the budget's spend (not its forecast) reaches the threshold, the hourly evaluation writes one
proposal for the period. It lists, inside the budget's scope and matching the selector:

- running instances, except Kubernetes nodes and members of an autoscaling group;
- for a matching instance that is a member of an autoscaling group, the group instead, when it is
  active and not already at zero, to be scaled to 0 (minimum and desired), with its sizes before;
- databases that are available.

Each item carries the hourly charge it would stop. Untagged resources never match, and a resource
tagged `budget-action=keep` is never proposed. A proposal holds at most 50 items. If nothing
matches, no proposal is written, and the next hour tries again. The budget's notification addresses
are mailed the list.

## Approve or dismiss a proposal

**Console**
1. Open **Budgets**. Pending proposals are under **Proposed by budgets**.
2. Choose **Approve: stop … resources**, or **Dismiss**.

Each item then shows its **Result** and **Detail**. The page shows at most six recent proposals,
pending ones first; dismissed and expired proposals are listed only over the CLI and the API.

**CLI**
```sh
dcloud billing budget-proposals list
dcloud billing budget-proposals approve proposal-id
```

**API**
```http
POST /billing/api/budgets/action-proposals/proposal-id/approve
```

**Terraform:** not available. A proposal is a decision for a person, not a resource.

Approving runs each stop through the resource's own API with your credentials, so each is checked
against your policies and recorded in the audit log as yours. Each item gets a result: `done`,
`skipped` (the resource could no longer be stopped, for example because someone stopped it first) or
`failed`, with the reason. Dismissing stops nothing, and the budget proposes nothing more this
period. A proposal nobody decides expires when the period ends.

To undo an approval, start the resources again, or set each group back to the `previous` sizes the
proposal shows.

## When a decision is refused

- `403` "Forbidden: you may not stop any of these resources. Nothing was stopped, and the proposal
  stays pending for someone who may." when every stop was refused for your permissions.
- `409` "This proposal is …; only a pending one can be approved." when it was already decided or has
  expired, and "This proposal is …, not pending." when dismissing one.
- `404` when the proposal is not in your organization. The proposal is looked up before your
  permission is checked.

## Related

- [Budgets](budgets.md)
- [Create a budget](create-a-budget.md)
- `billing.budget-proposals.approve` · `dcloud billing budget-proposals approve`
